Creating a Query
Ehcache uses a fluent, object-oriented query API, following the principles of a Domain-Specific Language (DSL), which should be familiar to Java programmers. For example:
Query query = cache.createQuery().addCriteria(age.eq(35)).includeKeys().end();
Results results = query.execute();
Using Attributes in Queries
If declared and available, the well-known attributes are referenced by their names or the convenience attributes are used directly:
Results results = cache.createQuery().addCriteria(Query.KEY.eq(35)).execute();
Results results = cache.createQuery().addCriteria(Query.VALUE.lt(10)).execute();
Other attributes are referenced by the names in the configuration:
Attribute<Integer> age = cache.getSearchAttribute("age");
Attribute<String> gender = cache.getSearchAttribute("gender");
Attribute<String> name = cache.getSearchAttribute("name");
Expressions
A Query is built up using Expressions. Expressions can include logical operators such as <and> and <or>, and comparison operators such as <ge> (>=), <between>, and <like>. The configuration, addCriteria(...), is used to add a clause to a query. Adding a further clause automatically “<and>s” the clauses.
query = cache.createQuery().includeKeys()
.addCriteria(age.le(65))
.add(gender.eq("male"))
.end();
Both logical and comparison operators implement the Criteria interface. To add a criterion with a different logical operator, explicitly nest it within a new logical operator Criteria object. For example, to check for age = 35 or gender = female:
query.addCriteria(new Or(age.eq(35),
gender.eq(Gender.FEMALE))
);
More complex compound expressions can be created through additional nesting. For a complete list of expressions, see the Expression Javadoc at
http://ehcache.org/xref/net/sf/ehcache/search/expression/package-frame.html.
List of Operators
Operators are available as methods on attributes, so they are used by adding a “.”. For example, “lt” means “less than” and is used as age.lt(10), which is a shorthand way of saying age LessThan(10).
Shorthand | Criteria Class | Description |
and | And | The Boolean AND logical operator. |
between | Between | A comparison operator meaning between two values. |
eq | EqualTo | A comparison operator meaning Java “equals to” condition. |
gt | GreaterThan | A comparison operator meaning greater than. |
ge | GreaterThanOrEqual | A comparison operator meaning greater than or equal to. |
in | InCollection | A comparison operator meaning in the collection given as an argument. |
lt | LessThan | A comparison operator meaning less than. |
le | LessThanOrEqual | A comparison operator meaning less than or equal to. |
ilike | ILike | A regular expression matcher. “?” and “*” may be used. Note that placing a wildcard in front of the expression will cause a table scan. ILike is always case insensitive. |
isNull | IsNull | Tests whether the value of an attribute with given name is null. |
notNull | NotNull | Tests whether the value of an attribute with given name is NOT null. |
not | Not | The Boolean NOT logical operator, |
ne | NotEqualTo | A comparison operator meaning not the Java “equals to” condition, |
or | Or | The Boolean OR logical operator. |
Note: | For Strings, the operators are case-insensitive. |
Making Queries Immutable
By default, a query can be executed, modified, and re-executed. If end( ) is called, the query is made immutable.