org.pajes.db.entity
Class Scope

java.lang.Object
  org.pajes.db.entity.Scope

All Implemented Interfaces:

java.io.Serializable

public class Scope

extends java.lang.Object

implements java.io.Serializable

Creates a WHERE clause suitable for use with a SQL select, update or delete java.sql.PreparedStatement. The resulting WHERE clause is NOT checked for syntactical accuracy.

The clause is built up by applying the and() and or() methods, followed by the appropriate comparison methods (compare(), between() and isNull()). For example:

 	Scope clause = new Scope()
 	.leftBrace()
 	.compare("colA",Scope.EQ,"XYZ")
 	.and()
 	.between("colB",new Integer(1),new Integer(10))
 	.rightBrace()
 	.or()
 	.compare("colC",Scope.GT,new Long(9999))
 	.or()
 	.isNull("colC")
 	System.out.println(clause.getWhereClause());
 

The above example would result in the following WHERE clause:

 	WHERE ( colA = ? AND colB BETWEEN ? AND ? ) OR colC > ? or colC IS NULL
 

and a call to clauses.getParameters() would return an Object array with 4 elements, representing the values passed into the compare and between methods.

See Also:

Serialized Form

Field Summary

static java.lang.String	AND Constant representing the AND conjunction operator.
static java.lang.String	BETWEEN Constant representing the BETWEEN conjunction operator.
static java.lang.String	EQ Constant representing the equals operator.
static java.lang.String	GE Constant representing the greater than or equal to operator.
static java.lang.String	GT Constant representing the greater than operator.
static java.lang.String	IN Constant representing the IN conjunction operator.
static java.lang.String	LE Constant representing the less than or equal to operator.
static java.lang.String	LIKE Constant representing the LIKE operator.
static java.lang.String	LT Constant representing the less than operator.
static java.lang.String	NE Constant representing the inequality operator.
static java.lang.String	NOT Constant representing the "not" modifier.
static java.lang.String	OR Constant representing the or conjunction operator.

Constructor Summary

Scope()
Creates a WHERE clause suitable for use with a SQL select, update or delete statement.

Scope(Entity entity)
Creates a scope consisting of the primary key values of the specified Entity.

Scope(Entity entity, boolean initial)
Creates a scope consisting of all the values assigned to an Entity, except those flagged as not participating in the optimistic lock key.

Scope(Manager manager, javax.servlet.http.HttpServletRequest request)
Creates a WHERE clause suitable for use with a SQL select, update or delete statement for the primary keys defined for Entity objects managed by the specified Manager.

Scope(Manager manager, javax.servlet.http.HttpServletRequest request, java.lang.String operator, boolean keys)
Creates a WHERE clause suitable for use with a SQL select, update or delete statement for the column names defined for Entity objects managed by the specified Manager.

Scope(Scope scope)
Creates a Scope from another Scope.

Scope(java.lang.String where, java.lang.Object[] values)
Creates a Scope from a supplied WHERE clause suitable for use with a SQL select, update or delete statement.

Scope(java.lang.String columnName, java.lang.String operator, java.lang.Object value)
Creates a WHERE clause suitable for use with a SQL select, update or delete statement, with a default comparison clause.

Method Summary

Scope	and() Appends an AND statement.
Scope	between(java.lang.String columnName, java.lang.Object lowerValue, java.lang.Object upperValue) Appends a BETWEEN comparison.
Scope	compare(Entity entity) Appends equalitycomparisons, joined by and operators, consisting of the primary key values of the specified Entity and the current value.
Scope	compare(Entity entity, boolean initial) Appends equalitycomparisons, joined by and operators, consisting of all the values assigned of the specified Entity, except those flagged as not participating in the optimistic lock key.
Scope	compare(Entity entity, boolean initial, boolean keys) Appends equalitycomparisons, joined by and operators, consisting of all the values assigned of the specified Entity, except those flagged as not participating in the optimistic lock key.
Scope	compare(javax.servlet.http.HttpServletRequest request, Manager manager, java.lang.String operator, boolean keys) Appends comparisons created by checking the parameter names supplied on the HttpServletRequest with the column names determined from the specified Entity Manager.
Scope	compare(javax.servlet.http.HttpServletRequest request, Manager manager, java.lang.String operator, boolean keys, boolean qualifyColumnName) Appends comparisons created by checking the parameter names supplied on the HttpServletRequest with the column names determined from the specified Entity Manager.
Scope	compare(java.lang.String columnName, java.lang.String operator, java.lang.Object value) Appends the specified comparison.
Scope	compareColumns(java.lang.String leftColumnName, java.lang.String operator, java.lang.String rightColumnName) Appends the specified comparison between two columns.
java.util.Set	getColumnNames() Returns the set of column names that have been defined on this scope.
java.lang.String	getJoinClause() Returns the join clause.
java.lang.Object[]	getJoinParameters() Returns the join parameters that can be substituted into the join clause.
java.lang.String	getOrderByClause() Returns the ORDER BY clause to sort the result set.
java.lang.String	getOrderByColumns() Returns the ORDER BY columns defined by setOrderByColumns(java.lang.String).
java.lang.Object[]	getParameters() Returns the parameters that can be substituted into the where clause.
java.lang.String	getSelectColumns() Returns the columns to be returned in the result set.
java.lang.String	getSelectTable() Returns the table to which the WHERE clause will apply.
java.lang.String	getTableAlias() Returns the table alias.
java.lang.String	getWhereClause() Returns the where clause as a string, with placeholders where values are to be substituted.
boolean	hasConditions() Determines if any conditions have been set on this scope.
boolean	hasJoins() Determines if any joins have been set on this scope.
boolean	hasOrderBy() Determines if an ORDER BY clause has been set on this scope.
Scope	in(java.lang.String columnName, java.lang.Object[] values) Appends an IN comparison to the where clause.
Scope	in(java.lang.String columnName, java.lang.String subSelect, Scope subSelectScope) Appends a sub query to the where clause.
Scope	innerJoin(java.lang.String table, JoinScope scope) Creates an INNER JOIN clause.
Scope	isNotNull(java.lang.String columnName) Appends an IS NOT NULL comparison to the where clause.
Scope	isNull(java.lang.String columnName) Appends an IS NULL comparison to the where clause.
Scope	isNull(java.lang.String columnName, boolean notNull) Appends a NULL comparison to the where clause.
Scope	leftBrace() Appends a left Brace to begin logical statement grouping.
Scope	leftOuterJoin(java.lang.String table, JoinScope scope) Creates a LEFT OUTER JOIN clause.
java.util.List	lookup(java.lang.String columnName) Returns the list of values that have been provided in the Scope for the specified column name.
Scope	merge(Scope scope) Merges another Scope into this Scope.
Scope	merge(java.lang.String where, java.lang.Object[] values) Merges a supplied WHERE clause into this Scope.
Scope	not() Appends a NOT statement.
Scope	or() Appends an OR statement.
Scope	rightBrace() Appends a right Brace to end logical statement grouping.
Scope	setOrderByColumns(java.lang.String columns) Sets the sort order of the result set.
Scope	setOrderByColumns(java.lang.String[] columns) Sets the sort order of the result set.
Scope	setSelectColumns(java.lang.String columns) Sets the columns returned in the result set.
Scope	setSelectColumns(java.lang.String[] columns) Sets the columns returned in the result set.
void	setSelectTable(java.lang.String tableString) Sets the table to which the WHERE clause will apply.
Scope	setTableAlias(java.lang.String alias) Sets the table alias.
Scope	subQuery(java.lang.String columnName, java.lang.String operator, java.lang.String subSelect, Scope subSelectScope) Appends a sub query to the where clause.
java.lang.String	toString() Returns a string representation of the scope.

Methods inherited from class java.lang.Object

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

Field Detail

AND

public static final java.lang.String AND

Constant representing the AND conjunction operator.

See Also:

Constant Field Values

BETWEEN

public static final java.lang.String BETWEEN

Constant representing the BETWEEN conjunction operator.

See Also:

Constant Field Values

EQ

public static final java.lang.String EQ

Constant representing the equals operator.

See Also:

Constant Field Values

GE

public static final java.lang.String GE

Constant representing the greater than or equal to operator.

See Also:

Constant Field Values

GT

public static final java.lang.String GT

Constant representing the greater than operator.

See Also:

Constant Field Values

IN

public static final java.lang.String IN

Constant representing the IN conjunction operator.

See Also:

Constant Field Values

LE

public static final java.lang.String LE

Constant representing the less than or equal to operator.

See Also:

Constant Field Values

LIKE

public static final java.lang.String LIKE

Constant representing the LIKE operator.

See Also:

Constant Field Values

LT

public static final java.lang.String LT

Constant representing the less than operator.

See Also:

Constant Field Values

NE

public static final java.lang.String NE

Constant representing the inequality operator.

See Also:

Constant Field Values

NOT

public static final java.lang.String NOT

Constant representing the "not" modifier.

See Also:

Constant Field Values

OR

public static final java.lang.String OR

Constant representing the or conjunction operator.

See Also:

Constant Field Values

Constructor Detail

Scope

public Scope()

Creates a WHERE clause suitable for use with a SQL select, update or delete statement.

Scope

public Scope(Entity entity)

Creates a scope consisting of the primary key values of the specified Entity. If the Entity has no primary keys defined, the scope will cover all of the values assigned to the Entity.

Parameters:

entity - the Entity for which a scope is required.

Scope

public Scope(Entity entity,
             boolean initial)

Creates a scope consisting of all the values assigned to an Entity, except those flagged as not participating in the optimistic lock key.

Parameters:

entity - the Entity for which a scope is required.

initial - true if the values provided are the initial values of the attributes.

Scope

public Scope(Manager manager,
             javax.servlet.http.HttpServletRequest request)

Creates a WHERE clause suitable for use with a SQL select, update or delete statement for the primary keys defined for Entity objects managed by the specified Manager.

The Scope will be created by checking the parameter names supplied on the HttpServletRequest, and, where the name matches a primary key column name, creating a compare(java.lang.String, java.lang.String, java.lang.Object) for each parameter value, using the EQ operator. Multiple values will be joined with or() statements within appropriately placed left and right brackets. Multiple column names will be joined with and() statements.

Parameters:

manager - the Manager object from which the primary column names will be determined.

request - the request object from which the comparison values will be determined.

Scope

public Scope(Manager manager,
             javax.servlet.http.HttpServletRequest request,
             java.lang.String operator,
             boolean keys)

Creates a WHERE clause suitable for use with a SQL select, update or delete statement for the column names defined for Entity objects managed by the specified Manager.

The Scope will be created by checking the parameter names supplied on the HttpServletRequest, and, where the name matches a column name, creating a compare(java.lang.String, java.lang.String, java.lang.Object) for each parameter value, using the specified operator. Multiple values will be joined with or() statements within appropriately placed left and right brackets. Multiple column names will be joined with and() statements.

Parameters:

manager - the Manager object from which the column names will be determined.

request - the request object from which the comparison values will be determined.

operator - the comparison operator.

keys - if true, limit the columns that will be included in the scope to the primary keys. If false, any column for which a request parameter is found will be included in the scope.

Scope

public Scope(Scope scope)

Creates a Scope from another Scope.

Parameters:

scope - the existing Scope to be the source for this scope.

Scope

public Scope(java.lang.String where,
             java.lang.Object[] values)

Creates a Scope from a supplied WHERE clause suitable for use with a SQL select, update or delete statement.

Parameters:

where - the base WHERE clause, including the WHERE statement. Care should be taken to ensure that the correct number of place holders appear in this String to match the number of values supplied the array.

values - the array of comparison values. Care should be taken to ensure that the number of values in the array matches the number of place holders in the supplied WHERE clause string, and be in the correct sequence in the array.

Scope

public Scope(java.lang.String columnName,
             java.lang.String operator,
             java.lang.Object value)

Creates a WHERE clause suitable for use with a SQL select, update or delete statement, with a default comparison clause.

Parameters:

columnName - the name of the column.

operator - the comparison operator.

value - the comparison value.

Method Detail

getColumnNames

public java.util.Set getColumnNames()

Returns the set of column names that have been defined on this scope. Each entry in the set is an upper-caseString.

Returns:

the the set of column names.

See Also:

lookup(java.lang.String)

getJoinClause

public java.lang.String getJoinClause()

Returns the join clause.

Returns:

the join clause, or an empty string if no joins have been defined.

See Also:

innerJoin(java.lang.String, org.pajes.db.entity.JoinScope), leftOuterJoin(java.lang.String, org.pajes.db.entity.JoinScope)

getJoinParameters

public java.lang.Object[] getJoinParameters()

Returns the join parameters that can be substituted into the join clause.

Returns:

an array of the Objects that correspond to the placeholders in the join clause.

isNotNull

public Scope isNotNull(java.lang.String columnName)

Appends an IS NOT NULL comparison to the where clause.

Parameters:

columnName - the name of the column.

Returns:

the modified Scope object.

isNull

public Scope isNull(java.lang.String columnName)

Appends an IS NULL comparison to the where clause.

Parameters:

columnName - the name of the column.

Returns:

the modified Scope object.

isNull

public Scope isNull(java.lang.String columnName,
                    boolean notNull)

Appends a NULL comparison to the where clause.

Parameters:

columnName - the name of the column.

notNull - if false, append "IS NULL", else if true append "IS NOT NULL".

Returns:

the modified Scope object.

getOrderByClause

public java.lang.String getOrderByClause()

Returns the ORDER BY clause to sort the result set.

Returns:

the complete ORDER BY clause, or an empty String if no sort columns have been defined.

See Also:

setOrderByColumns(java.lang.String), getOrderByColumns()

setOrderByColumns

public Scope setOrderByColumns(java.lang.String columns)

Sets the sort order of the result set.

Parameters:

columns - the comma separated list of columns that will be used in the ORDER BY clause.

Returns:

the modified Scope object.

setOrderByColumns

public Scope setOrderByColumns(java.lang.String[] columns)

Sets the sort order of the result set.

Parameters:

columns - the array of column names that will be used in the ORDER BY clause.

Returns:

the modified Scope object.

getOrderByColumns

public java.lang.String getOrderByColumns()

Returns the ORDER BY columns defined by setOrderByColumns(java.lang.String).

Returns:

the ORDER BY columns, or null if no sort columns have been defined.

See Also:

setOrderByColumns(java.lang.String), getOrderByClause()

getParameters

public java.lang.Object[] getParameters()

Returns the parameters that can be substituted into the where clause.

Returns:

an array of the Objects that correspond to the placeholders in the where clause.

setSelectColumns

public Scope setSelectColumns(java.lang.String columns)

Sets the columns returned in the result set.

Parameters:

columns - the comma separated list of columns that will be used in the SELECT statement.

Returns:

the modified Scope object.

setSelectColumns

public Scope setSelectColumns(java.lang.String[] columns)

Sets the columns returned in the result set.

Parameters:

columns - the array of column names that will be used in the SELECT statement.

Returns:

the modified Scope object.

getSelectColumns

public java.lang.String getSelectColumns()

Returns the columns to be returned in the result set.

Returns:

the columns to be returned in the result set.

setSelectTable

public void setSelectTable(java.lang.String tableString)

Sets the table to which the WHERE clause will apply.

Parameters:

tableString - the string representing the source table.

getSelectTable

public java.lang.String getSelectTable()

Returns the table to which the WHERE clause will apply.

Returns:

the table.

setTableAlias

public Scope setTableAlias(java.lang.String alias)

Sets the table alias. The current table alias is always pre-pended to the column name if the column name is not already qualified (i.e. if it does not contain a period (.)).

Parameters:

alias - The table alias. Use null to remove the table alias.

Returns:

the modified Scope object.

getTableAlias

public java.lang.String getTableAlias()

Returns the table alias.

Returns:

the table alias.

getWhereClause

public java.lang.String getWhereClause()

Returns the where clause as a string, with placeholders where values are to be substituted.

Returns:

the where clause.

See Also:

getParameters()

and

public Scope and()

Appends an AND statement. If the Scope has no conditions, the AND is NOT appended!

Returns:

the modified Scope object.

between

public Scope between(java.lang.String columnName,
                     java.lang.Object lowerValue,
                     java.lang.Object upperValue)

Appends a BETWEEN comparison.

Parameters:

columnName - the name of the column.

lowerValue - the lower comparison value.

upperValue - the upper comparison value.

Returns:

the modified Scope object.

compare

public Scope compare(java.lang.String columnName,
                     java.lang.String operator,
                     java.lang.Object value)

Appends the specified comparison.

Parameters:

columnName - the name of the column.

operator - the comparison operator.

value - the comparison value.

Returns:

the modified Scope object.

compare

public Scope compare(Entity entity)

Appends equalitycomparisons, joined by and operators, consisting of the primary key values of the specified Entity and the current value. If the Entity has no primary keys defined, all of the values assigned to the Entity will be used.

Parameters:

entity - the Entity from which the column names and values will be determined.

Returns:

the modified Scope object.

compare

public Scope compare(Entity entity,
                     boolean initial)

Appends equalitycomparisons, joined by and operators, consisting of all the values assigned of the specified Entity, except those flagged as not participating in the optimistic lock key.

Parameters:

entity - the Entity from which the column names and values will be determined.

initial - true if the values provided are the initial values of the attributes.

Returns:

the modified Scope object.

compare

public Scope compare(Entity entity,
                     boolean initial,
                     boolean keys)

Appends equalitycomparisons, joined by and operators, consisting of all the values assigned of the specified Entity, except those flagged as not participating in the optimistic lock key.

Parameters:

entity - the Entity from which the column names and values will be determined.

initial - true if the values provided are the initial values of the attributes.

Returns:

the modified Scope object.

compare

public Scope compare(javax.servlet.http.HttpServletRequest request,
                     Manager manager,
                     java.lang.String operator,
                     boolean keys)

Appends comparisons created by checking the parameter names supplied on the HttpServletRequest with the column names determined from the specified Entity Manager. Where the name matches a column name, this method will create a compare(java.lang.String, java.lang.String, java.lang.Object) for each parameter value, using the specified operator. Multiple values will be joined with or() statements within appropriately placed left and right brackets. Multiple column names will be joined with and() statements.

Parameters:

request - the request object from which the comparison values will be determined.

manager - the Manager object from which the column names will be determined.

operator - the comparison operator.

keys - if true, limit the columns that will be included in the scope to the primary keys. If false, any column for which a request parameter is found will be included in the scope.

Returns:

the modified Scope object.

compare

public Scope compare(javax.servlet.http.HttpServletRequest request,
                     Manager manager,
                     java.lang.String operator,
                     boolean keys,
                     boolean qualifyColumnName)

Appends comparisons created by checking the parameter names supplied on the HttpServletRequest with the column names determined from the specified Entity Manager. Where the name matches a column name, this method will create a compare(java.lang.String, java.lang.String, java.lang.Object) for each parameter value, using the specified operator. Multiple values will be joined with or() statements within appropriately placed left and right brackets. Multiple column names will be joined with and() statements.

Parameters:

request - the request object from which the comparison values will be determined.

manager - the Manager object from which the column names will be determined.

operator - the comparison operator.

keys - if true, limit the columns that will be included in the scope to the primary keys. If false, any column for which a request parameter is found will be included in the scope.

qualifyColumnName - true uses the qualified column name, false leaves off the table qualification.

Returns:

the modified Scope object.

compareColumns

public Scope compareColumns(java.lang.String leftColumnName,
                            java.lang.String operator,
                            java.lang.String rightColumnName)

Appends the specified comparison between two columns.

Parameters:

leftColumnName - the name of the column on the left of the comparison.

operator - the comparison operator.

rightColumnName - the name of the column on the right of the comparison.

Returns:

the modified Scope object.

hasConditions

public boolean hasConditions()

Determines if any conditions have been set on this scope.

Returns:

true if any conditions have been set on this scope.

hasJoins

public boolean hasJoins()

Determines if any joins have been set on this scope.

Returns:

true if any joins have been set on this scope.

hasOrderBy

public boolean hasOrderBy()

Determines if an ORDER BY clause has been set on this scope.

Returns:

true if an ORDER BY clause has been set on this scope.

in

public Scope in(java.lang.String columnName,
                java.lang.Object[] values)

Appends an IN comparison to the where clause.

Parameters:

columnName - the name of the column.

values - the array of values to be included.

Returns:

the modified Scope object.

Throws:

EntityException - if the specified Object array to create the values for the IN clause is empty.

See Also:

not()

in

public Scope in(java.lang.String columnName,
                java.lang.String subSelect,
                Scope subSelectScope)

Appends a sub query to the where clause.

Parameters:

columnName - the name of the column.

subSelect - the "SELECT column FROM table" portion of the sub-query.

subSelectScope - the Scope object to be applied as the WHERE clause for the sub-query.

Returns:

the modified Scope object.

See Also:

not(), subQuery(java.lang.String, java.lang.String, java.lang.String, org.pajes.db.entity.Scope)

innerJoin

public Scope innerJoin(java.lang.String table,
                       JoinScope scope)

Creates an INNER JOIN clause.

Parameters:

table - the table on the RIGHT side of the join.

scope - the scope describing the join ON clause.

Returns:

the modified Scope object.

leftBrace

public Scope leftBrace()

Appends a left Brace to begin logical statement grouping.

Returns:

the modified Scope object.

leftOuterJoin

public Scope leftOuterJoin(java.lang.String table,
                           JoinScope scope)

Creates a LEFT OUTER JOIN clause.

Parameters:

table - the table on the RIGHT side of the join.

scope - the scope describing the join ON clause.

Returns:

the modified Scope object.

lookup

public java.util.List lookup(java.lang.String columnName)

Returns the list of values that have been provided in the Scope for the specified column name.

Parameters:

columnName - the name of the column.

Returns:

a List of values. Each entry in the list will either be the specified value (if the value was provided as part of an equality comparision, or the space-separated operator and value(s) for any other type of operator. If no values have been provided for the specified column name, null will be returned.

See Also:

getColumnNames()

merge

public Scope merge(Scope scope)

Merges another Scope into this Scope.

Note that only the WHERE clause clause is merged: the ORDER BY clause and the SELECT columns are ignored.

Parameters:

scope - the Scope to be merged with this Scope.

Returns:

the modified Scope object.

merge

public Scope merge(java.lang.String where,
                   java.lang.Object[] values)

Merges a supplied WHERE clause into this Scope.

Parameters:

where - the base WHERE clause. If this String starts with a WHERE statement, it will be stripped off. Care should be taken to ensure that the correct number of place holders appear in this String to match the number of values supplied the array.

values - the array of comparison values. Care should be taken to ensure that the number of values in the array matches the number of place holders in the supplied WHERE clause string, and be in the correct sequence in the array.

Returns:

the modified Scope object.

not

public Scope not()

Appends a NOT statement. The only logical use is before an in(java.lang.String, java.lang.Object[]) statement.

Returns:

the modified Scope object.

or

public Scope or()

Appends an OR statement. If the Scope has no conditions, the OR is NOT appended!

Returns:

the modified Scope object.

rightBrace

public Scope rightBrace()

Appends a right Brace to end logical statement grouping.

Returns:

the modified Scope object.

subQuery

public Scope subQuery(java.lang.String columnName,
                      java.lang.String operator,
                      java.lang.String subSelect,
                      Scope subSelectScope)

Appends a sub query to the where clause.

Parameters:

columnName - the name of the column.

operator - the comparison operator.

subSelect - the "SELECT column FROM table" portion of the sub-query.

subSelectScope - the Scope object to be applied as the WHERE clause for the sub-query.

Returns:

the modified Scope object.

toString

public java.lang.String toString()

Returns a string representation of the scope. Note that this string may NOT suitable for submission to a SQL database.

Returns:

the scope as a string.