Creating search criteria is the same as entering Filter Criteria for a custom search. To create filter criteria, use one of the two search() methods that accept SearchCriteria. Depending on your filter criteria, you can construct SearchCriteria in one of three ways:
•SearchCriteria()—Searching for one type of record.
•SearchCriteria(FieldCriterion fieldCriterion)—Searching with one filter criteria.
•SearchCriteria(SearchExpression expr1, SearchExpression expr2, SearchExpression... expressions)—Searching with multiple filter criteria.
Searching for One Type of Record
To return all records of a specific type, use an empty SearchCriteria(). For example, if you want to return all records for one project type, pass in the project's unique code and SearchCriteria(), as shown in the following sample.
// Using an empty search criteria to return all Disputes List<Project> allDisputes = platform.getProjectService().search("DISP", new SearchCriteria()); |
Searching with One Filter Criteria
To search with one filter criteria, use SearchCriteria(FieldCriterion fieldCriterion). Use FieldCriterion to enter the fields you are searching on and its subclasses when you know the data types of those fields. Along with the field, you include the value of the field that determines the search results.
For example, if you want to search for all appointments in Room 101, you can use the code in the following sample.
// Retrieve the appointment service from the platform provided by the API. AppointmentService appointmentService = platform.getAppointmentService();
// Find all appointments located in Room 101 StringCriterion locationCriterion = new StringCriterion(Appointment.LOCATION).equalTo("Room 101"); SearchCriteria criteria = new SearchCriteria(locationCriterion);
// Execute search List<Appointment> results = appointmentService.search(criteria); |
The previous sample uses the following code to build search criteria:
•Appointment.LOCATION for searching on a system field.
•equalTo("Room 101") for setting the operator.
Searching with Multiple Filter Criteria
To search with multiple filter criteria, use SearchCriteria(SearchExpression expr1, SearchExpression expr2, SearchExpression... expressions). SearchExpression allows you to search during the following scenarios.
All or Any Criteria as Part of the Results
You may want to search with more than one filter criteria and you want all or any of the criteria to be part of the results. For all the criteria, use the and() method. For any of the criteria, use the or() method.
The following code sample provides an example of using the or() method to join date criteria and combining the date criteria with the and() method.
// Retrieve the appointment service from the platform provided by the API. AppointmentService appointmentService = platform.getAppointmentService();
// Find all appointments located in Room 101 SearchCriteria criteria = new SearchCriteria(new StringCriterion(Appointment.LOCATION).equalTo("Room 101"));
// Find appointments starting within four days or ending in the next two days RelativeDateCriterion startOnCriterion = new RelativeDateCriterion(Appointment.START_ON).next(4); RelativeDateCriterion endOnCriterion = new RelativeDateCriterion(Appointment.END_ON).next(2);
// Join the two date criteria, specifying 'or' logic SearchCriteria dateCriteria = startOnCriterion.or(endOnCriterion);
// Join the date criteria and location criteria criteria.and(dateCriteria);
// Execute search and return results List<Appointment> results = appointmentService.search(criteria); |
The previous sample includes the following code:
•The first search expression uses one filter criteria to specify that the results return all appointments in Room 101.
SearchCriteria criteria = new SearchCriteria(new StringCriterion(Appointment.LOCATION).equalTo("Room 101")); |
•The second search expression specifies relative date criteria using the next() method and combines them with the or() method to specify whether the search returns the applicable start date or end date.
RelativeDateCriterion startOnCriterion = new RelativeDateCriterion(Appointment.START_ON).next(4); RelativeDateCriterion endOnCriterion = new RelativeDateCriterion(Appointment.END_ON).next(2);
SearchCriteria dateCriteria = startOnCriterion.or(endOnCriterion); |
•The sample combines both of the previous expressions.
criteria.and(dateCriteria); |
•The code executes.
List<Appointment> results = appointmentService.search(criteria); |
Complex Criteria to Determine Results
You may want to specify whether some and which criteria should be, should possibly be, or should not be part of the results. You can use a different method for each search criteria:
•You can specify that the search must include two search conditions with and().
•You can specify that either search condition should appear in the search results using or().
•You can specify conditions for results that you do not want to include using not().
The following code sample provides an example of the previous scenario.
// Get service AppointmentService appointmentService = platform.getAppointmentService();
// Group One: In Room 101 AND All Day StringCriterion locationCriterion = new StringCriterion(Appointment.LOCATION).equalTo("Room 101"); BooleanCriterion allDayCriterion = new BooleanCriterion(Appointment.ALL_DAY).isTrue(); SearchCriteria andGroup = locationCriterion.and(allDayCriterion);
// Group Two: Started within the last 5 days OR ends in the next 3 days RelativeDateCriterion startOnCriterion = new RelativeDateCriterion(Appointment.START_ON).withinLast(5); RelativeDateCriterion endOnCriterion = new RelativeDateCriterion(Appointment.END_ON).next(3); SearchCriteria orGroup = startOnCriterion.or(endOnCriterion);
// Composite Group: NOT in both group one and group two SearchCriteria notGroup = new SearchCriteria(andGroup, orGroup).not();
// Execute search and return results return appointmentService.search(notGroup); |
The previous sample includes the following code:
•The first search expression specifies all day-long appointments in Room 101.
StringCriterion locationCriterion = new StringCriterion(Appointment.LOCATION).equalTo("Room 101"); BooleanCriterion allDayCriterion = new BooleanCriterion(Appointment.ALL_DAY).isTrue(); SearchCriteria andGroup = locationCriterion.and(allDayCriterion); |
•The second search expression specifies all appointments that started in the last 5 days or end in the next 3 days.
RelativeDateCriterion startOnCriterion = new RelativeDateCriterion(Appointment.START_ON).withinLast(5); RelativeDateCriterion endOnCriterion = new RelativeDateCriterion(Appointment.END_ON).next(3); SearchCriteria orGroup = startOnCriterion.or(endOnCriterion); |
•The third search expression specifies all appointments not part of the other two expressions.
SearchCriteria notGroup = new SearchCriteria(andGroup, orGroup).not(); |
•The sample searches for all results that the third expression returns as part of its execution.
appointmentService.search(notGroup); |
Note: This code uses the and(SearchExpression expression) method instead of the and() method because it combines multiple filter criteria with additional search expressions. If the AND or OR applies to all filter criteria, use the and() or or() methods.
