Search (Sakai Entity Broker API 10.4 API)

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

Fields
Modifier and Type Field and Description

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

Fields
Modifier and Type	Field and Description
`boolean`	`conjunction` if true then all restrictions are run using AND, if false then all restrictions are run using OR

Constructor Summary

Constructors
Constructor and Description
`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

Methods
Modifier and Type	Method and Description
`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

Class Search

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

conjunction

Constructor Detail

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Search

Method Detail

setStart

getStart

setLimit

getLimit

isConjunction

setConjunction

getRestrictions

setRestrictions

getOrders

setOrders

getQueryString

setQueryString

addRestriction

addOrder

getRestrictionByProperty

getRestrictionsProperties

getRestrictionByProperties

getRestrictionValueByProperties

isEmpty

reset

contains

appendArray

arrayToString

clone

copy

equals

hashCode

toString