Package org.apache.juneau.commons.beanquery

Class BeanQuerySession<T>

java.lang.Object

org.apache.juneau.commons.beanquery.BeanQuerySession<T>

Type Parameters:

T - The row (bean) type.

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

InMemoryBeanQuerySession, SqlBeanQuerySession

public abstract class BeanQuerySession<T>
extends Object
implements AutoCloseable

One unit of query work against a BeanQueryContext: the rows (or connection) to query, plus optional per-request narrowing of the context's settings.

Open a session per request and close it with try-with-resources. A session is not thread-safe. Its public methods are final: each validates the BeanQuery into a ResolvedQuery (throwing BeanQuerySyntaxException for bad input) and then calls the engine's doXxx hook. Engine failures throw BeanQueryExecutionException.

BeanQuerySession.Builder.restrictColumns(String...) only narrows the context's columns. The limit, cap and count-policy overrides replace the context's values for this session (so they can also raise or remove a cap); they are for trusted server-side callers only, never request data.

Example:

// Shortcut: the context's settings as-is. try (InMemoryBeanQuerySession<Person> session = context.getSession(rows)) { Page<Person> page = session.find(query); } // Narrowed for a guest user. try (InMemoryBeanQuerySession<Person> session = context.createSession() .rows(rows) .restrictColumns("name", "city") .defaultLimit(20) .maxLimit(20) .build()) { List<Map<String,Object>> values = session.findValues(query).rows(); }

Since:

10.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	BeanQuerySession.Builder<T,SELF extends BeanQuerySession.Builder<T,SELF>>	The settings every engine's session builder shares.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	BeanQuerySession(BeanQuerySession.Builder<T,?> builder)	Constructor.

Method Summary

Modifier and Type	Method	Description
abstract void	close()	Releases whatever the session acquired.
final List<String>	columns()	Returns this session's columns, in order (the context's columns after any restriction).
final Counts	count(BeanQuery query)	Returns both counts, whatever the CountPolicy.
protected abstract Counts	doCount(ResolvedQuery query)	Engine hook for count(BeanQuery).
protected abstract Page<T>	doFind(ResolvedQuery query)	Engine hook for find(BeanQuery).
protected abstract Page<Map<String,Object>>	doFindValues(ResolvedQuery query)	Engine hook for findValues(BeanQuery).
protected abstract Stream<T>	doStream(ResolvedQuery query)	Engine hook for stream(BeanQuery).
protected abstract Stream<Map<String,Object>>	doStreamValues(ResolvedQuery query)	Engine hook for streamValues(BeanQuery).
final Page<T>	find(BeanQuery query)	Returns one page of matching rows, plus the counts the CountPolicy selects.
final Page<Map<String,Object>>	findValues(BeanQuery query)	Like find(BeanQuery), but each row is a map of the viewed columns, in view order.
BeanQueryContext<T>	getContext()	Returns the context that created this session (through BeanQueryContext.createSession() or an engine's getSession(...) shortcut).
final int	getMaxSearchClauses()	Returns the largest number of search clauses a query may use in this session: the context's cap, or this session's override.
final int	getMaxSortKeys()	Returns the largest number of sort keys a query may use in this session: the context's cap, or this session's override.
protected static <R> Page<R>	page(List<R> rows, ResolvedQuery query, LongSupplier total, LongSupplier matched)	Builds a page, computing only the counts the query's policy selects.
final ResolvedQuery	resolve(BeanQuery query)	Validates a query against this session's rules without running it.
final Stream<T>	stream(BeanQuery query)	Streams one page of matching rows.
final Stream<Map<String,Object>>	streamValues(BeanQuery query)	Like stream(BeanQuery), but each row is a map of the viewed columns, in view order.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

BeanQuerySession

protected BeanQuerySession(BeanQuerySession.Builder<T,?> builder)

Constructor. Takes a private copy of the builder's settings and validates it.

Parameters:

builder - The builder. Must not be null.

Throws:

IllegalStateException - If the settings are invalid.

Method Details

columns

public final List<String> columns()

Returns this session's columns, in order (the context's columns after any restriction).

Returns:

An unmodifiable list.

getContext

public BeanQueryContext<T> getContext()

Returns the context that created this session (through BeanQueryContext.createSession() or an engine's getSession(...) shortcut).

Engines whose session builder is given a narrower context type (for example, InMemoryBeanQuerySession) override this with a covariant return type.

Returns:

The context. Never null.

getMaxSearchClauses

public final int getMaxSearchClauses()

Returns the largest number of search clauses a query may use in this session: the context's cap, or this session's override.

Returns:

The cap.

getMaxSortKeys

public final int getMaxSortKeys()

Returns the largest number of sort keys a query may use in this session: the context's cap, or this session's override.

Returns:

The cap.

resolve

public final ResolvedQuery resolve(BeanQuery query)

Validates a query against this session's rules without running it.

Parameters:

query - The query. Must not be null.

Returns:

The resolved query.

Throws:

BeanQuerySyntaxException - If the query breaks a rule.

find

public final Page<T> find(BeanQuery query)

Returns one page of matching rows, plus the counts the CountPolicy selects.

Parameters:

query - The query. Must not be null.

Returns:

The page.

Throws:

BeanQuerySyntaxException - If the query breaks a rule.

BeanQueryExecutionException - If the engine fails.

findValues

public final Page<Map<String,Object>> findValues(BeanQuery query)

Like find(BeanQuery), but each row is a map of the viewed columns, in view order.

Parameters:

query - The query. Must not be null.

Returns:

The page.

Throws:

BeanQuerySyntaxException - If the query breaks a rule.

BeanQueryExecutionException - If the engine fails.

count

public final Counts count(BeanQuery query)

Returns both counts, whatever the CountPolicy. Sort, view and paging are ignored.

Parameters:

query - The query. Must not be null.

Returns:

The counts.

Throws:

BeanQuerySyntaxException - If the query breaks a rule.

BeanQueryExecutionException - If the engine fails.

stream

public final Stream<T> stream(BeanQuery query)

Streams one page of matching rows. Close the stream (or the session) to release engine resources.

Parameters:

query - The query. Must not be null.

Returns:

The rows.

Throws:

BeanQuerySyntaxException - If the query breaks a rule.

BeanQueryExecutionException - If the engine fails.

streamValues

public final Stream<Map<String,Object>> streamValues(BeanQuery query)

Like stream(BeanQuery), but each row is a map of the viewed columns, in view order.

Parameters:

query - The query. Must not be null.

Returns:

The rows.

Throws:

BeanQuerySyntaxException - If the query breaks a rule.

BeanQueryExecutionException - If the engine fails.

doFind

protected abstract Page<T> doFind(ResolvedQuery query)

Engine hook for find(BeanQuery).

Parameters:

query - The validated query.

Returns:

The page. Build it with page(List, ResolvedQuery, LongSupplier, LongSupplier).

doFindValues

protected abstract Page<Map<String,Object>> doFindValues(ResolvedQuery query)

Engine hook for findValues(BeanQuery).

Parameters:

query - The validated query.

Returns:

The page.

doCount

protected abstract Counts doCount(ResolvedQuery query)

Engine hook for count(BeanQuery).

Parameters:

query - The validated query.

Returns:

The counts.

doStream

protected abstract Stream<T> doStream(ResolvedQuery query)

Engine hook for stream(BeanQuery).

Parameters:

query - The validated query.

Returns:

The rows.

doStreamValues

protected abstract Stream<Map<String,Object>> doStreamValues(ResolvedQuery query)

Engine hook for streamValues(BeanQuery).

Parameters:

query - The validated query.

Returns:

The rows.

page

protected static <R> Page<R> page(List<R> rows,
 ResolvedQuery query,
 LongSupplier total,
 LongSupplier matched)

Builds a page, computing only the counts the query's policy selects.

Type Parameters:

R - The row type.

Parameters:

rows - The page's rows.

query - The validated query.

total - Computes the total count. Called only under CountPolicy.BOTH.

matched - Computes the matched count. Called only under CountPolicy.MATCHED or CountPolicy.BOTH.

Returns:

The page.

close

public abstract void close()

Releases whatever the session acquired. Never throws a checked exception.

Specified by:

close in interface AutoCloseable