Package org.apache.juneau.commons.beanquery

package org.apache.juneau.commons.beanquery
A protocol-agnostic query API for filtering, sorting, and paging collections of beans (design §5).

A BeanQuery carries only raw strings: one search string of column=expression clauses in the $-language, plus raw view/sort directives, position/ limit, and an open opts bag. The clause grammar shared by search and opts is decoded by ClauseParser; the single public SearchExpressionParser then parses each clause's expression against a SearchOperatorSet, throwing BeanQuerySyntaxException on an unknown operator or a malformed expression.

A BeanQueryContext is the immutable, thread-safe half: its columns, operators and limits are fixed by a builder (create()...build(); copy() derives a variant). Per request it opens a BeanQuerySession, which may narrow the columns, override the limits and add a guard. Every query is validated into a ResolvedQuery before any engine runs it; rule violations throw BeanQuerySyntaxException (client error) and engine failures throw BeanQueryExecutionException (server error). Results come back as Pages with the counts the CountPolicy selects.

The InMemoryBeanQueryContext runs against an in-JVM collection. SQL engines live in separate modules: juneau-beanquery-sql supplies the shared JDBC context and the SqlDialect hook under org.apache.juneau.beanquery.sql. Commons carries the query API only, not the SQL dialect types.

Example:

static final InMemoryBeanQueryContext<Person> PEOPLE = InMemoryBeanQueryContext .create(Person.class) .exclude("password") .maxLimit(500) .build(); try (InMemoryBeanQuerySession<Person> session = PEOPLE.getSession(people)) { Page<Person> page = session.find(BeanQuery.create() .setSearch("age=$gt(21)") .setSort("name") .setLimit(20)); }