org.josef.jpa

Class WhereClause

java.lang.Object

org.josef.jpa.WhereClause

@Status(stage=TEST,
        unitTests=COMPLETE)
 @Review(by="Kees Schotanus",
        at="2009-10-08",
        reason="After creation of unit tests")
public class WhereClause
extends Object

Abstraction of a JP/QL where clause.
This class assists in creating a where clause. It shines when search criteria have been entered by a user and all the different expressions must be anded together. Here is an example that searches for org.josef.demo.jpa.Element Elements.

final WhereClause whereClause = new WhereClause();
 whereClause.addRelationalExpression("e.id", RelationalOperator.EQUAL, getNumber());
 whereClause.addRelationalExpression("e.symbol", RelationalOperator.EQUAL, getSymbol());
 whereClause.addStartsWith("e.name", getName());
 whereClause.addBetween("e.weight", getFromWeight(), getToWeight());
 

The resulting where clause looks like this:
e.id=?1 AND e.symbol=?2 AND e.name LIKE ?3 AND e.weight BETWEEN ?4 AND ?5
By using getParameters() you can get all the parameters that need to be inserted into the where clause.

Version:

1.0 $Revision: 6488 $

Author:

Kees Schotanus

Constructor Summary

Constructors

Constructor and Description
WhereClause()

Method Summary

Modifier and Type	Method and Description
void	addAndExpression(String leftOperand, String rightOperand) Adds a boolean AND expression to this WhereClause that is created from the supplied leftOperand and rightOperand.
void	addAsIs(String expression) Adds the supplied expression as-is to this WhereClause.
void	addBetween(String column, Object minimum, Object maximum) Adds a BETWEEN expression to this WhereClause that is created from the supplied column and minimum and maximum values.
void	addEndsWith(String column, String value) Adds a LIKE expression (where the percent sign is at the beginning of the expression) to this WhereClause that is created from the supplied column and value.
void	addExpression(String expression) Adds the supplied expression to this WhereClause.
static String	addFunctionCall(SingleParamFunction function, String expression) Creates a function call from the supplied function and parameter.
void	addIsNotNull(String column) Adds an IS NOT NULL expression to this WhereClause that is created from the supplied column.
void	addIsNull(String column) Adds an IS NULL expression to this WhereClause that is created from the supplied column.
void	addOrExpression(String leftOperand, String rightOperand) Adds a boolean OR expression to this WhereClause that is created from the supplied leftOperand and rightOperand.
void	addRelationalExpression(String column, RelationalOperator operator, Object value) Adds a relational expression to this WhereClause that is created from the supplied column, operator and value.
void	addStartsWith(String column, String value) Adds a LIKE expression (where the percent sign is at the end of the expression) to this WhereClause that is created from the supplied column and value.
List<Object>	getParameters() Gets all the JP/QL parameters.
String	toString() Creates a String representation of this WhereClause.

Methods inherited from class java.lang.Object

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

Constructor Detail

WhereClause

public WhereClause()

Method Detail

addAsIs

public void addAsIs(String expression)

Adds the supplied expression as-is to this WhereClause.
Only when the current WhereClause is not empty, an extra space is appended to this WhereClause before adding the supplied expression.
Note: No expression is added when the supplied expression is null or empty.

Parameters:

expression - The expression to add as-is to this WhereClause.

addExpression

public void addExpression(String expression)

Adds the supplied expression to this WhereClause.
Only when the current WhereClause is not empty, an AND is appended to this WhereClause before adding the expression.
Note: No expression is added when the supplied expression is null or empty.

Parameters:

expression - The expression to add to this WhereClause.

addAndExpression

public void addAndExpression(String leftOperand,
                             String rightOperand)

Adds a boolean AND expression to this WhereClause that is created from the supplied leftOperand and rightOperand.
Only when the current WhereClause is not empty, an AND is appended to this WhereClause before adding the expression.

Parameters:

leftOperand - The operand to the left of the AND.

rightOperand - The operand to the right of the AND.

Throws:

IllegalArgumentException - When either the supplied leftOperand or rightOperand is empty.

NullPointerException - When either the supplied leftOperand or rightOperand is null.

addOrExpression

public void addOrExpression(String leftOperand,
                            String rightOperand)

Adds a boolean OR expression to this WhereClause that is created from the supplied leftOperand and rightOperand.
Only when the current WhereClause is not empty, an AND is appended to this WhereClause before adding the expression.

Parameters:

leftOperand - The operand to the left of the OR.

rightOperand - The operand to the right of the OR.

Throws:

IllegalArgumentException - When either the supplied leftOperand or rightOperand is empty.

NullPointerException - When either the supplied leftOperand or rightOperand is null.

addRelationalExpression

public void addRelationalExpression(String column,
                                    RelationalOperator operator,
                                    Object value)

Adds a relational expression to this WhereClause that is created from the supplied column, operator and value.
Only when the current WhereClause is not empty, an AND is appended to this WhereClause before adding the expression.
Note: No expression is added when the supplied value is null, or is of type String and is empty.

Parameters:

column - The column.

operator - The relational operator to apply.

value - The value.

Throws:

IllegalArgumentException - When the supplied column is empty.

NullPointerException - When either the supplied column or operator is null.

addStartsWith

public void addStartsWith(String column,
                          String value)

Adds a LIKE expression (where the percent sign is at the end of the expression) to this WhereClause that is created from the supplied column and value.
Only when the current WhereClause is not empty, an AND is appended to this WhereClause before adding the expression.
Note: No expression is added when the supplied value is null or empty.
Note: This method has build in protection against the supplied value already containing a wild-card character. In such cases the '%' wild-card character is not added.

Parameters:

column - The column.

value - The value.

Throws:

IllegalArgumentException - When the supplied column is empty.

NullPointerException - When the supplied column is null.

addEndsWith

public void addEndsWith(String column,
                        String value)

Adds a LIKE expression (where the percent sign is at the beginning of the expression) to this WhereClause that is created from the supplied column and value.
Only when the current WhereClause is not empty, an AND is appended to this WhereClause before adding the expression.
Note: No expression is added when the supplied value is null or empty.
Note: This method has build in protection against the supplied value already containing a wild-card character. In such cases the '%' wild-card character is not added.

Parameters:

column - The column.

value - The value.

Throws:

IllegalArgumentException - When the supplied column is empty.

NullPointerException - When the supplied column is null.

addBetween

public void addBetween(String column,
                       Object minimum,
                       Object maximum)

Adds a BETWEEN expression to this WhereClause that is created from the supplied column and minimum and maximum values.
Only when the current WhereClause is not empty, an AND is appended to this WhereClause before adding the expression.
Note: No expression is added when both minimum and maximum are null.

Parameters:

column - The column.

minimum - The minimum value.

maximum - The maximum value.

Throws:

IllegalArgumentException - When the supplied column is empty.

NullPointerException - When the supplied column is null.

addIsNull

public void addIsNull(String column)

Adds an IS NULL expression to this WhereClause that is created from the supplied column.
Only when the current WhereClause is not empty, an AND is appended to this WhereClause before adding the expression.

Parameters:

column - The column.

Throws:

IllegalArgumentException - When the supplied column is empty.

NullPointerException - When the supplied column is null.

addIsNotNull

public void addIsNotNull(String column)

Adds an IS NOT NULL expression to this WhereClause that is created from the supplied column.
Only when the current WhereClause is not empty, an AND is appended to this WhereClause before adding the expression.

Parameters:

column - The column.

Throws:

IllegalArgumentException - When the supplied column is empty.

NullPointerException - When the supplied column is null.

addFunctionCall

public static String addFunctionCall(SingleParamFunction function,
                                     String expression)

Creates a function call from the supplied function and parameter.

Parameters:

function - The function to call.

expression - The expression that is the parameter to the function.

Returns:

The function call.

Throws:

IllegalArgumentException - When either the supplied function or expression is empty.

NullPointerException - When either the supplied function or expression is null.

toString

public String toString()

Creates a String representation of this WhereClause.

Overrides:

toString in class Object

Returns:

A String representation of this WhereClause.
This does not include the "where" keyword itself.

getParameters

public List<Object> getParameters()

Gets all the JP/QL parameters.

Returns:

The JP/QL parameters.
The returned List may be empty but will never be null!