Package org.lockss.ws.status

package org.lockss.ws.status

SQL-Like Query

There are several operations that require as an argument a text string containing a SQL-like query used to determine the results to be returned.

The result of executing such a query is always a List of objects. The kind of objects populating the result List is specific to the web service operation being performed.
For example, the Daemon Status web service operation queryPlugins returns a List of PluginWsResult objects.

The query may have up to three clauses, each of them allowing the user to control a different aspect of the results. Each clause is separated from the other by at least one space.

The three clauses are, in order of appearance in the query:

  • A required select clause, which specifies which properties in the returned objects should be properly populated, while the rest are populated with null values.
    The text of the select clause begins with the word SELECT followed by a space and either a comma-separated list of property names or an asterisk (*):
    • If a list of property names is included, the names in the list must correspond to properties of the objects being returned. The property names may be obtained from the get* accessor method names by removing the leading "get" and changing the capitalization of the resulting first letter to lower case.
    • The asterisk (*) is a shorthand way of specifying all the property names.

  • An optional where clause, which specifies which objects have to be included in the results, while the rest are not.
    The text of the where clause begins with the word WHERE followed by a space and a space-separated list of conditions using OR and AND keywords to specify the filtering logic. Parentheses may be used in the typical grouping manner.
    Each condition is a comparison between properties of the objects being returned and other properties or between properties and constants using comparators like <, =, etc. Text constants must be surrounded by single quote (') characters.

  • An optional order by clause, which specifies the order of the objects in the List that contains the results.
    The text of the order by clause begins with the words ORDER BY followed by a space and a comma-separated list of property names, each of them optionally followed by the keyword ASC (default) or DESC.

Examples

  1. select *: It is the simplest (but costly) query and it results in a List of all the objects with each and every property properly populated.
  2. select name: Results in a List of all the objects with just the name property properly populated and the rest of properties populated with null values.
  3. select name where id > 10: Results in a List of the objects with the numeric id property greater than 10 only and properly populated with just the name property and the rest of properties populated with null values.
  4. select id where name = 'abc': Results in a List of the objects with the text name property equal to abc only and properly populated with just the id property and the rest of properties populated with null values.
  5. select id, name where value < 100 and color like 'red%' order by id: Results in a List of the objects with both the numeric value property lower than 100 and the text color property starting with red only and properly populated with just the id and name properties and the rest of properties populated with null values. The objects in the list are ordered from the smallest id property to the largest one.
  6. select id, longValue where toDate(longValue) < toDate('02/Apr/2014'): Results in a List of the objects with the long numeric longValue property representing a date before April 2, 2014 and properly populated with just the id and longValue properties and the rest of properties populated with null values.