org.sakaiproject.entitybroker.entityprovider.search
Class Search

java.lang.Object
  org.sakaiproject.entitybroker.entityprovider.search.Search

Direct Known Subclasses:

QuerySearch

public class Search
extends Object

This is a simple class which allows the passing of a set of search parameters in a nice way
Example usage:
Search s1 = new Search("title", curTitle); // search where title equals value of curTitle
Search s2 = new Search("title", curTitle, Restriction.NOT_EQUALS); // search where title not equals value of curTitle
Search s2 = new Search(
new Restriction("title", curTitle),
new Order("title")
); // search where title equals value of curTitle and order is by title ascending

Most searches can be modeled this way fairly easily. There are many constructors to make it easy for a developer to write the search they want inside the search constructor.
There are also some methods to allow easy construction of searches in multiple steps: addOrder(Order) and addRestriction(Restriction) allow restrictions and orders to be added after the search was constructed, they will correctly handle duplicate values as well.

There is also an option to pass a search string as well which can contain formatted text to be interpreted by whatever is using the search object

Finally, there are a few methods to make it easier to unpack and work with the search object: isEmpty() and getRestrictionByProperty(String) and getRestrictionsProperties() make it easier to get the restriction information out of the search object

Author:

Aaron Zeckoski (aaronz@caret.cam.ac.uk)

Field Summary

boolean

conjunction if true then all restrictions are run using AND, if false then all restrictions are run using OR

Constructor Summary

Search()
Empty constructor, if nothing is changed then this indicates that the search should return all items in default order

Search(Restriction restriction)
Defines a search which defines only a single restriction, defaults to AND restriction comparison and returning all results

Search(Restriction[] restrictions)
Defines a search which defines only restrictions, defaults to AND restriction comparisons and returning all results

Search(Restriction[] restrictions, Order order)
Defines a search which defines restrictions and return ordering, defaults to AND restriction comparisons and returning all results

Search(Restriction[] restrictions, Order[] orders)
Defines a search which defines restrictions and return ordering, defaults to AND restriction comparisons and returning all results

Search(Restriction[] restrictions, Order[] orders, long start, long limit)
Defines a search which defines restrictions and return ordering and limits the returns, defaults to AND restriction comparisons

Search(Restriction[] restrictions, Order[] orders, long start, long limit, boolean conjunction)
Defines a search which defines restrictions and return ordering and limits the returns, also specifies the types of restriction comparisons (AND or OR)

Search(Restriction[] restrictions, Order order, long start, long limit)
Defines a search which defines restrictions and return ordering and limits the returns, defaults to AND restriction comparisons

Search(Restriction[] restrictions, Order order, long start, long limit, boolean conjunction)
Defines a search which defines restrictions and return ordering and limits the returns, also specifies the types of restriction comparisons (AND or OR)

Search(Restriction restriction, Order order)
Defines a search which defines only a single restriction and returns all items, defaults to AND restriction comparisons

Search(Restriction restriction, Order order, long start, long limit)
Defines a search which defines only a single restriction and limits the returns, defaults to AND restriction comparisons

Search(Search search)
Copy constructor
Use this create a duplicate of a search object

Search(String queryString)
Do a search using a query string

Search(String[] properties, Object[] values)
Do a search of multiple properties which must equal corresponding values, all arrays should be the same length

Search(String[] properties, Object[] values, boolean conjunction)
Do a search of multiple properties which must equal corresponding values, control whether to do an AND or an OR between restrictions, all arrays should be the same length

Search(String[] properties, Object[] values, int[] comparisons)
Do a search of multiple properties which are compared with corresponding values, all arrays should be the same length

Search(String[] properties, Object[] values, int[] comparisons, boolean conjunction)
Do a search of multiple properties which are compared with corresponding values, all arrays should be the same length

Search(String[] properties, Object[] values, int[] comparisons, Order[] orders)
Do a search of multiple properties which are compared with corresponding values, sort the returned results in ascending order defined by specific sortProperties, all arrays should be the same length

Search(String[] properties, Object[] values, int[] comparisons, Order[] orders, long firstResult, long maxResults)
Do a search of multiple properties which are compared with corresponding values, sort the returned results in ascending order defined by specific sortProperties, all arrays should be the same length

Search(String property, Object value)
Do a simple search of a single property which must equal a single value

Search(String property, Object value, int comparison)
Do a simple search of a single property with a single type of comparison

Method Summary

void	addOrder(Order order)
void	addRestriction(Restriction restriction)
static <T> T[]	appendArray(T[] array, T value) Append an item to the end of an array and return the new array
static String	arrayToString(Object[] array) Utility method to convert an array to a string
protected Object	clone()
static <T> int	contains(T[] array, T value) Checks to see if an array contains a value, will return the position of the value or -1 if not found
static Search	copy(Search original, Search copy) Make a copy of a search object
boolean	equals(Object obj)
long	getLimit()
Order[]	getOrders() Orders define the order of the returned results of a search, You can add as many orders as you like and they will be applied in the array order
String	getQueryString() Defines a search query string which will be interpreted into search params, If not null this indicates that this is a string based "search" The search string is just text - there is no required structure nor any modifiers.
Restriction	getRestrictionByProperties(String[] properties) Finds if there are any search restrictions with one of the given properties, if so it returns the first of the found restriction, otherwise returns null
Restriction	getRestrictionByProperty(String property) Convenient method to find restrictions by their property, if there happens to be more than one restriction with a property then only the first one will be returned (since that is an invalid state)
Restriction[]	getRestrictions() Restrictions define limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump' You can add as many restrictions as you like and they will be applied in the array order
List<String>	getRestrictionsProperties()
Object	getRestrictionValueByProperties(String[] properties) Finds if there are any search restrictions with one of the given properties, if so it returns the first non-null value in the found restrictions, otherwise returns null
long	getStart()
int	hashCode()
boolean	isConjunction() if true then all restrictions are run using AND, if false then all restrictions are run using OR
boolean	isEmpty()
void	reset() Resets the search object to empty state
void	setConjunction(boolean conjunction)
void	setLimit(long limit)
void	setOrders(Order[] orders)
void	setQueryString(String queryString)
void	setRestrictions(Restriction[] restrictions)
void	setStart(long start)
String	toString()

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

conjunction

public boolean conjunction

if true then all restrictions are run using AND, if false then all restrictions are run using OR

Constructor Detail

Search

public Search()

Empty constructor, if nothing is changed then this indicates that the search should return all items in default order

Search

public Search(Search search)

Copy constructor
Use this create a duplicate of a search object

Search

public Search(String queryString)

Do a search using a query string

Parameters:

queryString - a search query string, can be combined with other parts of the search object

See Also:

queryString

Search

public Search(String property,
              Object value)

Do a simple search of a single property which must equal a single value

Parameters:

property - the name of the field (property) in the persisted object

value - the value of the property (can be an array of items)

Search

public Search(String property,
              Object value,
              int comparison)

Do a simple search of a single property with a single type of comparison

Parameters:

property - the name of the field (property) in the persisted object

value - the value of the property (can be an array of items)

comparison - the comparison to make between the property and the value, use the defined constants from Restriction: e.g. EQUALS, LIKE, etc...

Search

public Search(String[] properties,
              Object[] values)

Do a search of multiple properties which must equal corresponding values, all arrays should be the same length

Parameters:

properties - the names of the properties of the object

values - the values of the properties (can be an array of items)

Search

public Search(String[] properties,
              Object[] values,
              boolean conjunction)

Do a search of multiple properties which must equal corresponding values, control whether to do an AND or an OR between restrictions, all arrays should be the same length

Parameters:

properties - the names of the properties of the object

values - the values of the properties (can be an array of items)

conjunction - if true then all restrictions are run using AND, if false then all restrictions are run using OR

Search

public Search(String[] properties,
              Object[] values,
              int[] comparisons)

Do a search of multiple properties which are compared with corresponding values, all arrays should be the same length

Parameters:

properties - the names of the properties of the object

values - the values of the properties (can be an array of items)

comparisons - the comparison to make between the property and the value, use the defined constants from Restriction: e.g. EQUALS, LIKE, etc...

Search

public Search(String[] properties,
              Object[] values,
              int[] comparisons,
              boolean conjunction)

Do a search of multiple properties which are compared with corresponding values, all arrays should be the same length

Parameters:

properties - the names of the properties of the object

values - the values of the properties (can be an array of items)

comparisons - the comparison to make between the property and the value, use the defined constants from Restriction: e.g. EQUALS, LIKE, etc...

conjunction - if true then all restrictions are run using AND, if false then all restrictions are run using OR

Search

public Search(String[] properties,
              Object[] values,
              int[] comparisons,
              Order[] orders)

Do a search of multiple properties which are compared with corresponding values, sort the returned results in ascending order defined by specific sortProperties, all arrays should be the same length

Parameters:

properties - the names of the properties of the object

values - the values of the properties (can be an array of items)

comparisons - the comparison to make between the property and the value, use the defined constants from Restriction: e.g. EQUALS, LIKE, etc...

orders - orders to sort the returned results by

Search

public Search(String[] properties,
              Object[] values,
              int[] comparisons,
              Order[] orders,
              long firstResult,
              long maxResults)

Do a search of multiple properties which are compared with corresponding values, sort the returned results in ascending order defined by specific sortProperties, all arrays should be the same length

Parameters:

properties - the names of the properties of the object

values - the values of the properties (can be an array of items)

comparisons - the comparison to make between the property and the value, use the defined constants from Restriction: e.g. EQUALS, LIKE, etc...

orders - orders to sort the returned results by

firstResult - the index of the first persisted result object to be retrieved (numbered from 0)

maxResults - the maximum number of persisted result objects to retrieve (or <=0 for no limit)

Search

public Search(Restriction restriction)

Defines a search which defines only a single restriction, defaults to AND restriction comparison and returning all results

Parameters:

restriction - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

Search

public Search(Restriction[] restrictions)

Defines a search which defines only restrictions, defaults to AND restriction comparisons and returning all results

Parameters:

restrictions - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

Search

public Search(Restriction restriction,
              Order order)

Defines a search which defines only a single restriction and returns all items, defaults to AND restriction comparisons

Parameters:

restriction - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

order - define the order of the returned results of a search (only one order)

Search

public Search(Restriction[] restrictions,
              Order order)

Defines a search which defines restrictions and return ordering, defaults to AND restriction comparisons and returning all results

Parameters:

restrictions - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

order - define the order of the returned results of a search (only one order)

Search

public Search(Restriction[] restrictions,
              Order[] orders)

Defines a search which defines restrictions and return ordering, defaults to AND restriction comparisons and returning all results

Parameters:

restrictions - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

orders - define the order of the returned results of a search, You can add as many orders as you like and they will be applied in the array order

Search

public Search(Restriction restriction,
              Order order,
              long start,
              long limit)

Defines a search which defines only a single restriction and limits the returns, defaults to AND restriction comparisons

Parameters:

restriction - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

order - define the order of the returned results of a search (only one order)

start - the index of the first persisted result object to be retrieved (numbered from 0)

limit - the maximum number of persisted result objects to retrieve (or <=0 for no limit)

Search

public Search(Restriction[] restrictions,
              Order order,
              long start,
              long limit)

Defines a search which defines restrictions and return ordering and limits the returns, defaults to AND restriction comparisons

Parameters:

restrictions - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

order - define the order of the returned results of a search (only one order)

start - the index of the first persisted result object to be retrieved (numbered from 0)

limit - the maximum number of persisted result objects to retrieve (or <=0 for no limit)

Search

public Search(Restriction[] restrictions,
              Order[] orders,
              long start,
              long limit)

Defines a search which defines restrictions and return ordering and limits the returns, defaults to AND restriction comparisons

Parameters:

restrictions - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

orders - define the order of the returned results of a search, You can add as many orders as you like and they will be applied in the array order

start - the index of the first persisted result object to be retrieved (numbered from 0)

limit - the maximum number of persisted result objects to retrieve (or <=0 for no limit)

Search

public Search(Restriction[] restrictions,
              Order order,
              long start,
              long limit,
              boolean conjunction)

Defines a search which defines restrictions and return ordering and limits the returns, also specifies the types of restriction comparisons (AND or OR)

Parameters:

restrictions - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

order - define the order of the returned results of a search (only one order)

start - the index of the first persisted result object to be retrieved (numbered from 0)

limit - the maximum number of persisted result objects to retrieve (or <=0 for no limit)

conjunction - if true then all restrictions are run using AND, if false then all restrictions are run using OR

Search

public Search(Restriction[] restrictions,
              Order[] orders,
              long start,
              long limit,
              boolean conjunction)

Defines a search which defines restrictions and return ordering and limits the returns, also specifies the types of restriction comparisons (AND or OR)

Parameters:

restrictions - define the limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

orders - define the order of the returned results of a search, You can add as many orders as you like and they will be applied in the array order

start - the index of the first persisted result object to be retrieved (numbered from 0)

limit - the maximum number of persisted result objects to retrieve (or <=0 for no limit)

conjunction - if true then all restrictions are run using AND, if false then all restrictions are run using OR

Method Detail

setStart

public void setStart(long start)

getStart

public long getStart()

setLimit

public void setLimit(long limit)

getLimit

public long getLimit()

isConjunction

public boolean isConjunction()

if true then all restrictions are run using AND, if false then all restrictions are run using OR

setConjunction

public void setConjunction(boolean conjunction)

getRestrictions

public Restriction[] getRestrictions()

Restrictions define limitations on the results of a search, e.g. propertyA > 100 or property B = 'jump'
You can add as many restrictions as you like and they will be applied in the array order

setRestrictions

public void setRestrictions(Restriction[] restrictions)

getOrders

public Order[] getOrders()

Orders define the order of the returned results of a search, You can add as many orders as you like and they will be applied in the array order

setOrders

public void setOrders(Order[] orders)

getQueryString

public String getQueryString()

Defines a search query string which will be interpreted into search params, If not null this indicates that this is a string based "search"
The search string is just text - there is no required structure nor any modifiers. It is a freeform string.
Effectively the semantics are that it can be implemented in a relational database using like clauses for the relevant text fields - or perhaps just submitted to lucene and see which entities match.
If this is being sent to lucene - things like order, and restrictions might actually be added to the lucene query in addition to the simple search string.

setQueryString

public void setQueryString(String queryString)

addRestriction

public void addRestriction(Restriction restriction)

Parameters:

restriction - add this restriction to the search filter, will replace an existing restriction for a similar property

addOrder

public void addOrder(Order order)

Parameters:

order - add this order to the search filter, will replace an existing order for a similar property

getRestrictionByProperty

public Restriction getRestrictionByProperty(String property)

Convenient method to find restrictions by their property, if there happens to be more than one restriction with a property then only the first one will be returned (since that is an invalid state)

Parameters:

property - the property to match

Returns:

the Restriction with this property or null if none found

getRestrictionsProperties

public List<String> getRestrictionsProperties()

Returns:

a list of all the properties on all restrictions in this search filter object

getRestrictionByProperties

public Restriction getRestrictionByProperties(String[] properties)

Finds if there are any search restrictions with one of the given properties, if so it returns the first of the found restriction, otherwise returns null

Parameters:

properties - an array of the properties (e.g. 'name','age') to find a value for

Returns:

the value OR null if none found

getRestrictionValueByProperties

public Object getRestrictionValueByProperties(String[] properties)

Finds if there are any search restrictions with one of the given properties, if so it returns the first non-null value in the found restrictions, otherwise returns null

Parameters:

properties - an array of the properties (e.g. 'name','age') to find a value for

Returns:

the value OR null if none found

isEmpty

public boolean isEmpty()

Returns:

true if this search has no defined restrictions and no orders (i.e. this is a default search so return everything in default order), false if there are any defined restrictions or orders

reset

public void reset()

Resets the search object to empty state

contains

public static <T> int contains(T[] array,
                               T value)

Checks to see if an array contains a value, will return the position of the value or -1 if not found

Type Parameters:

T -

Parameters:

array - any array of objects

value - the value to check for

Returns:

array position if found, -1 if not found

appendArray

public static <T> T[] appendArray(T[] array,
                                  T value)

Append an item to the end of an array and return the new array

Parameters:

array - an array of items

value - the item to append to the end of the new array

Returns:

a new array with value in the last spot

arrayToString

public static String arrayToString(Object[] array)

Utility method to convert an array to a string

Parameters:

array - any array

Returns:

a string version of the array

clone

protected Object clone()
                throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

copy

public static Search copy(Search original,
                          Search copy)

Make a copy of a search object

Parameters:

original - the search object to copy

copy - the search object make equivalent to the original, can be null to generate a new one

Returns:

the copy of the original

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object