org.forgerock.json.resource

Interface QueryRequest

All Superinterfaces:

Request

public interface QueryRequest
extends Request

A request to search for all JSON resources matching a user specified set of criteria.

There are four types of query request:

• default query: when neither a filter, expression or query ID are specified all resources will be returned
• query by filter: returns all resources which match the QueryFilters specified using QueryRequest.setQueryFilter(QueryFilter)
• query by ID: returns all resources which match the named prepared query specified using QueryRequest.setQueryId(String)
• query by expression: returns all resources which match a native expression specified using QueryRequest.setQueryExpression(String). Note that this type of query should only be used in very rare cases since it introduces a tight coupling between the application and the underlying JSON resource. In addition, applications should take care to prevent users from directly accessing this form of query for security reasons.

In addition to the above mentioned query types queries may also be paged when a page size is found via QueryRequest.getPageSize(). Paged requests should be used in most cases when an unknown number of query results will be returned.

Field Summary

Fields

Modifier and Type	Field and Description
static String	FIELD_PAGE_SIZE The name of the field which contains the page size in the JSON representation.
static String	FIELD_PAGED_RESULTS_COOKIE The name of the field which contains the paged results cookie in the JSON representation.
static String	FIELD_PAGED_RESULTS_OFFSET The name of the field which contains the paged results offset in the JSON representation.
static String	FIELD_QUERY_EXPRESSION The name of the field which contains the query expression in the JSON representation.
static String	FIELD_QUERY_FILTER The name of the field which contains the query filter in the JSON representation.
static String	FIELD_QUERY_ID The name of the field which contains the query ID in the JSON representation.
static String	FIELD_SORT_KEYS The name of the field which contains the sort keys in the JSON representation.
static String	FIELD_TOTAL_PAGED_RESULTS_POLICY The name of the field which contains the policy used for calculating the total number of paged results.

Fields inherited from interface org.forgerock.json.resource.Request

FIELD_ADDITIONAL_PARAMETERS, FIELD_FIELDS, FIELD_RESOURCE_PATH, FIELD_VALUE_ALL

Method Summary

Modifier and Type	Method and Description
<R,P> R	accept(RequestVisitor<R,P> v, P p) Applies a RequestVisitor to this Request.
QueryRequest	addField(JsonPointer... fields) Adds one or more fields which should be included with each JSON resource returned by this request.
QueryRequest	addField(String... fields) Adds one or more fields which should be included with each JSON resource returned by this request.
QueryRequest	addSortKey(SortKey... keys) Adds one or more sort keys which will be used for ordering the JSON resources returned by this query request.
QueryRequest	addSortKey(String... keys) Adds one or more sort keys which will be used for ordering the JSON resources returned by this query request.
String	getAdditionalParameter(String name) Returns the additional parameter which should be used to control the behavior of this action request.
Map<String,String>	getAdditionalParameters() Returns the additional parameters which should be used to control the behavior of this action request.
List<JsonPointer>	getFields() Returns the list of fields which should be included with each JSON resource returned by this request.
String	getPagedResultsCookie() Returns the opaque cookie which is used by the resource provider to track its position in the set of query results.
int	getPagedResultsOffset() Returns the zero-based index of the first resource which should be included in the query results.
int	getPageSize() Returns the requested page results page size or 0 if paged results are not required.
PreferredLocales	getPreferredLocales() Get the locale preference for the request.
String	getQueryExpression() Returns the native query expression which will be used for processing the query request.
QueryFilter<JsonPointer>	getQueryFilter() Returns the query filter which will be used for selecting which JSON resources will be returned.
String	getQueryId() Returns the query identifier for pre-defined queries.
RequestType	getRequestType() Returns the type of this request.
String	getResourcePath() Returns the non-null path of the JSON resource to which this request should be targeted.
ResourcePath	getResourcePathObject() Returns the non-null path of the JSON resource to which this request should be targeted.
Version	getResourceVersion() Gets the requested API version of the resource.
List<SortKey>	getSortKeys() Returns the sort keys which should be used for ordering the JSON resources returned by this query request.
CountPolicy	getTotalPagedResultsPolicy() Returns the CountPolicy used to calculate QueryResponse.getTotalPagedResults().
QueryRequest	setAdditionalParameter(String name, String value) Sets an additional parameter which should be used to control the behavior of this action request.
QueryRequest	setPagedResultsCookie(String cookie) Sets the opaque cookie which is used by the resource provider to track its position in the set of query results.
QueryRequest	setPagedResultsOffset(int offset) Sets the zero-based index of the first resource which should be included in the query results.
QueryRequest	setPageSize(int size) Sets the requested page results page size or 0 if paged results are not required.
QueryRequest	setPreferredLocales(PreferredLocales preferredLocales) Set the locale preference for the request.
QueryRequest	setQueryExpression(String expression) Sets the native query expression which will be used for processing the query request.
QueryRequest	setQueryFilter(QueryFilter<JsonPointer> filter) Sets the query filter which will be used for selecting which JSON resources will be returned.
QueryRequest	setQueryId(String id) Sets the query identifier for pre-defined queries.
QueryRequest	setResourcePath(ResourcePath path) Sets the non-null path of the JSON resource to which this request should be targeted.
QueryRequest	setResourcePath(String path) Sets the non-null path of the JSON resource to which this request should be targeted.
QueryRequest	setResourceVersion(Version resourceVersion) Sets the requested API version of the resource.
QueryRequest	setTotalPagedResultsPolicy(CountPolicy policy) Sets the policy for calculating the total number of paged results.
JsonValue	toJsonValue() Return a JsonValue representation of this request.

Field Detail

FIELD_PAGED_RESULTS_COOKIE

static final String FIELD_PAGED_RESULTS_COOKIE

The name of the field which contains the paged results cookie in the JSON representation.

See Also:

Constant Field Values

FIELD_PAGED_RESULTS_OFFSET

static final String FIELD_PAGED_RESULTS_OFFSET

The name of the field which contains the paged results offset in the JSON representation.

See Also:

Constant Field Values

FIELD_PAGE_SIZE

static final String FIELD_PAGE_SIZE

The name of the field which contains the page size in the JSON representation.

See Also:

Constant Field Values

FIELD_QUERY_EXPRESSION

static final String FIELD_QUERY_EXPRESSION

The name of the field which contains the query expression in the JSON representation.

See Also:

Constant Field Values

FIELD_QUERY_FILTER

static final String FIELD_QUERY_FILTER

The name of the field which contains the query filter in the JSON representation.

See Also:

Constant Field Values

FIELD_QUERY_ID

static final String FIELD_QUERY_ID

The name of the field which contains the query ID in the JSON representation.

See Also:

Constant Field Values

FIELD_SORT_KEYS

static final String FIELD_SORT_KEYS

The name of the field which contains the sort keys in the JSON representation.

See Also:

Constant Field Values

FIELD_TOTAL_PAGED_RESULTS_POLICY

static final String FIELD_TOTAL_PAGED_RESULTS_POLICY

The name of the field which contains the policy used for calculating the total number of paged results.

See Also:

Constant Field Values

Method Detail

accept

<R,P> R accept(RequestVisitor<R,P> v,
               P p)

Description copied from interface: Request

Applies a RequestVisitor to this Request.

Specified by:

accept in interface Request

Type Parameters:

R - The return type of the visitor's methods.

P - The type of the additional parameters to the visitor's methods.

Parameters:

v - The request visitor.

p - Optional additional visitor parameter.

Returns:

A result as specified by the visitor.

addField

QueryRequest addField(JsonPointer... fields)

Description copied from interface: Request

Adds one or more fields which should be included with each JSON resource returned by this request.

Specified by:

addField in interface Request

Parameters:

fields - The fields which should be included with each JSON resource returned by this request.

Returns:

This request.

addField

QueryRequest addField(String... fields)

Description copied from interface: Request

Adds one or more fields which should be included with each JSON resource returned by this request.

Specified by:

addField in interface Request

Parameters:

fields - The fields which should be included with each JSON resource returned by this request.

Returns:

This request.

addSortKey

QueryRequest addSortKey(SortKey... keys)

Adds one or more sort keys which will be used for ordering the JSON resources returned by this query request.

Parameters:

keys - The sort keys which will be used for ordering the JSON resources returned by this query request.

Returns:

This query request.

Throws:

UnsupportedOperationException - If this query request does not permit changes to the sort keys.

addSortKey

QueryRequest addSortKey(String... keys)

Adds one or more sort keys which will be used for ordering the JSON resources returned by this query request.

Parameters:

keys - The sort keys which will be used for ordering the JSON resources returned by this query request.

Returns:

This query request.

Throws:

IllegalArgumentException - If one or more of the provided sort keys could not be parsed.

UnsupportedOperationException - If this query request does not permit changes to the sort keys.

getAdditionalParameter

String getAdditionalParameter(String name)

Description copied from interface: Request

Returns the additional parameter which should be used to control the behavior of this action request.

Specified by:

getAdditionalParameter in interface Request

Parameters:

name - The name of the additional parameter.

Returns:

The additional parameter which should be used to control the behavior of this action request

getAdditionalParameters

Map<String,String> getAdditionalParameters()

Description copied from interface: Request

Returns the additional parameters which should be used to control the behavior of this action request. The returned map may be modified if permitted by this action request.

Specified by:

getAdditionalParameters in interface Request

Returns:

The additional parameters which should be used to control the behavior of this action request (never null).

getFields

List<JsonPointer> getFields()

Description copied from interface: Request

Returns the list of fields which should be included with each JSON resource returned by this request. The returned list may be modified if permitted by this query request. An empty list indicates that all fields should be included.

NOTE: field filtering alters the structure of a JSON resource and MUST only be performed once while processing a request. It is therefore the responsibility of front-end implementations (e.g. HTTP listeners, Servlets, etc) to perform field filtering. Request handler and resource provider implementations SHOULD NOT filter fields, but MAY choose to optimise their processing in order to return a resource containing only the fields targeted by the field filters.

Specified by:

getFields in interface Request

Returns:

The list of fields which should be included with each JSON resource returned by this request (never null).

getPageSize

int getPageSize()

Returns the requested page results page size or 0 if paged results are not required. For all paged result requests other than the initial request, a cookie should be provided with the query request. See QueryRequest.getPagedResultsCookie() for more information.

Returns:

The requested page results page size or 0 if paged results are not required.

See Also:

QueryRequest.getPagedResultsCookie(), QueryRequest.getPagedResultsOffset()

getPagedResultsCookie

String getPagedResultsCookie()

Returns the opaque cookie which is used by the resource provider to track its position in the set of query results. Paged results will be enabled if and only if the page size is non-zero.

The cookie must be null in the initial query request sent by the client. For subsequent query requests the client must include the cookie returned with the previous query result, until the resource provider returns a null cookie indicating that the final page of results has been returned.

Note: Cookies and offsets are mutually exclusive.

Returns:

The opaque cookie which is used by the resource provider to track its position in the set of query results, or null if paged results are not requested (when the page size is 0) or if the first page of results is being requested (when the page size is non-zero).

See Also:

QueryRequest.getPageSize(), QueryRequest.getPagedResultsOffset()

getPagedResultsOffset

int getPagedResultsOffset()

Returns the zero-based index of the first resource which should be included in the query results. An offset of 0 (default) will return the first resource in the collection. An offset of 1 will return the second, and so on ...

Note: Offsets and cookies are mutually exclusive. When a cookie is supplied only the default 0 offset is supported.

Offset must be a zero-based integer denoting the number of records to skip. This is very similar to the LIMIT and SKIP clauses in SQL databases.

Returns:

The zero-based index within the result set of the first result which should be returned.

See Also:

QueryRequest.getPageSize(), QueryRequest.getPagedResultsCookie()

getPreferredLocales

PreferredLocales getPreferredLocales()

Description copied from interface: Request

Get the locale preference for the request.

Specified by:

getPreferredLocales in interface Request

Returns:

The PreferredLocales instance for the request.

getQueryExpression

String getQueryExpression()

Returns the native query expression which will be used for processing the query request. An example of a native query expression is a SQL statement.

NOTE: the native query expression, query filter, and query ID parameters are mutually exclusive and only one of them may be specified.

Returns:

The native query expression which will be used for processing the query request, or null if another type of query is to be performed.

See Also:

QueryRequest.getQueryFilter(), QueryRequest.getQueryId()

getQueryFilter

QueryFilter<JsonPointer> getQueryFilter()

Returns the query filter which will be used for selecting which JSON resources will be returned.

NOTE: the native query expression, query filter, and query ID parameters are mutually exclusive and only one of them may be specified.

Returns:

The query filter which will be used for selecting which JSON resources will be returned, or null if another type of query is to be performed.

See Also:

QueryRequest.getQueryExpression(), QueryRequest.getQueryId()

getQueryId

String getQueryId()

Returns the query identifier for pre-defined queries.

NOTE: the native query expression, query filter, and query ID parameters are mutually exclusive and only one of them may be specified.

Returns:

The query identifier for pre-defined queries, or null if a pre-defined query is not to be used, or null if another type of query is to be performed.

See Also:

QueryRequest.getQueryExpression(), QueryRequest.getQueryFilter()

getRequestType

RequestType getRequestType()

Description copied from interface: Request

Returns the type of this request.

Specified by:

getRequestType in interface Request

Returns:

The type of this request.

getResourcePath

String getResourcePath()

Description copied from interface: Request

Returns the non-null path of the JSON resource to which this request should be targeted. The resource path is relative and never begins or ends with a forward slash, but may be empty.

NOTE: for resource provider implementations the resource path is relative to the current resource being accessed. See the description of UriRouterContext for more information.

Specified by:

getResourcePath in interface Request

Returns:

The non-null path of the JSON resource to which this request should be targeted, which may be the empty string.

getResourcePathObject

ResourcePath getResourcePathObject()

Description copied from interface: Request

Returns the non-null path of the JSON resource to which this request should be targeted. The resource path is relative and never begins or ends with a forward slash, but may be empty.

NOTE: for resource provider implementations the resource path is relative to the current resource being accessed. See the description of UriRouterContext for more information.

Specified by:

getResourcePathObject in interface Request

Returns:

The non-null path of the JSON resource to which this request should be targeted, which may be the empty string.

getResourceVersion

Version getResourceVersion()

Description copied from interface: Request

Gets the requested API version of the resource.

Specified by:

getResourceVersion in interface Request

Returns:

The requested API version of the resource.

getSortKeys

List<SortKey> getSortKeys()

Returns the sort keys which should be used for ordering the JSON resources returned by this query request. The returned list may be modified if permitted by this query request.

Returns:

The sort keys which should be used for ordering the JSON resources returned by this query request (never null).

getTotalPagedResultsPolicy

CountPolicy getTotalPagedResultsPolicy()

Returns the CountPolicy used to calculate QueryResponse.getTotalPagedResults().

Returns:

The count policy.

See Also:

QueryResponse.getTotalPagedResults()

setAdditionalParameter

QueryRequest setAdditionalParameter(String name,
                                    String value)
                             throws BadRequestException

Description copied from interface: Request

Sets an additional parameter which should be used to control the behavior of this action request.

Specified by:

setAdditionalParameter in interface Request

Parameters:

name - The name of the additional parameter.

value - The additional parameter's value.

Returns:

This request.

Throws:

BadRequestException - If this request does not permit the additional parameter to be set.

setPageSize

QueryRequest setPageSize(int size)

Sets the requested page results page size or 0 if paged results are not required. For all paged result requests other than the initial request, a cookie should be provided with the query request. See QueryRequest.setPagedResultsCookie(String) for more information.

Parameters:

size - The requested page results page size or 0 if paged results are not required.

Returns:

This query request.

Throws:

UnsupportedOperationException - If this query request does not permit changes to the page size.

See Also:

QueryRequest.getPagedResultsCookie(), QueryRequest.setPagedResultsOffset(int)

setPagedResultsCookie

QueryRequest setPagedResultsCookie(String cookie)

Sets the opaque cookie which is used by the resource provider to track its position in the set of query results. Paged results will be enabled if and only if the page size is non-zero.

The cookie must be null in the initial query request sent by the client. For subsequent query requests the client must include the cookie returned with the previous query result, until the resource provider returns a null cookie indicating that the final page of results has been returned.

When subsequent paged requests are being made no query parameters may be altered; doing so will result in undefined behavior. The only parameter that may be changed during paged requests is the page size.

Parameters:

cookie - The opaque cookie which is used by the resource provider to track its position in the set of query results.

Returns:

This query request.

Throws:

UnsupportedOperationException - If this query request does not permit changes to the paged results cookie.

See Also:

QueryRequest.setPageSize(int), QueryRequest.addSortKey(SortKey...), QueryRequest.addSortKey(String...)

setPagedResultsOffset

QueryRequest setPagedResultsOffset(int offset)

Sets the zero-based index of the first resource which should be included in the query results. An offset of 0 (default) will return the first resource in the collection. An offset of 1 will return the second, and so on ...

Note: Offsets and cookies are mutually exclusive. When a cookie is supplied only the default 0 offset is supported.

Offset must be a zero-based integer denoting the number of records to skip. This is very similar to the LIMIT and SKIP clauses in SQL databases.

Parameters:

offset - The index within the result set of the first result which should be returned.

Returns:

This query request.

Throws:

UnsupportedOperationException - If this query request does not permit changes to the paged results offset.

See Also:

QueryRequest.setPageSize(int), QueryRequest.setPagedResultsCookie(String)

setPreferredLocales

QueryRequest setPreferredLocales(PreferredLocales preferredLocales)

Description copied from interface: Request

Set the locale preference for the request.

Specified by:

setPreferredLocales in interface Request

Parameters:

preferredLocales - The PreferredLocales instance for the request.

Returns:

This request.

setQueryExpression

QueryRequest setQueryExpression(String expression)

Sets the native query expression which will be used for processing the query request. An example of a native query expression is a SQL statement.

NOTE: the native query expression, query filter, and query ID parameters are mutually exclusive and only one of them may be specified.

Parameters:

expression - The native query expression which will be used for processing the query request, or null if another type of query is to be performed.

Returns:

This query request.

Throws:

UnsupportedOperationException - If this query request does not permit changes to the query identifier.

See Also:

QueryRequest.setQueryFilter(QueryFilter), QueryRequest.setQueryId(String)

setQueryFilter

QueryRequest setQueryFilter(QueryFilter<JsonPointer> filter)

Sets the query filter which will be used for selecting which JSON resources will be returned.

NOTE: the native query expression, query filter, and query ID parameters are mutually exclusive and only one of them may be specified.

Parameters:

filter - The query filter which will be used for selecting which JSON resources will be returned, or null if another type of query is to be performed.

Returns:

This query request.

Throws:

UnsupportedOperationException - If this query request does not permit changes to the query filter.

See Also:

QueryRequest.setQueryExpression(String), QueryRequest.setQueryId(String)

setQueryId

QueryRequest setQueryId(String id)

Sets the query identifier for pre-defined queries.

NOTE: the native query expression, query filter, and query ID parameters are mutually exclusive and only one of them may be specified.

Parameters:

id - The query identifier for pre-defined queries, or null if another type of query is to be performed.

Returns:

This query request.

Throws:

UnsupportedOperationException - If this query request does not permit changes to the query identifier.

See Also:

QueryRequest.setQueryExpression(String), QueryRequest.setQueryFilter(QueryFilter)

setResourcePath

QueryRequest setResourcePath(ResourcePath path)

Description copied from interface: Request

Sets the non-null path of the JSON resource to which this request should be targeted. The resource path is relative and never begins or ends with a forward slash, but may be empty.

NOTE: for resource provider implementations the resource path is relative to the current resource being accessed. See the description of UriRouterContext for more information.

Specified by:

setResourcePath in interface Request

Parameters:

path - The non-null path of the JSON resource to which this request should be targeted, which may be the empty string.

Returns:

This request.

setResourcePath

QueryRequest setResourcePath(String path)

Description copied from interface: Request

Sets the non-null path of the JSON resource to which this request should be targeted. The resource path is relative and never begins or ends with a forward slash, but may be empty.

NOTE: for resource provider implementations the resource path is relative to the current resource being accessed. See the description of UriRouterContext for more information.

Specified by:

setResourcePath in interface Request

Parameters:

path - The non-null path of the JSON resource to which this request should be targeted, which may be the empty string. The path should be URL-encoded.

Returns:

This request.

setResourceVersion

QueryRequest setResourceVersion(Version resourceVersion)

Description copied from interface: Request

Sets the requested API version of the resource.

Specified by:

setResourceVersion in interface Request

Parameters:

resourceVersion - The requested API version of the resource.

Returns:

This request.

setTotalPagedResultsPolicy

QueryRequest setTotalPagedResultsPolicy(CountPolicy policy)

Sets the policy for calculating the total number of paged results. If no count policy is supplied or paged results are not requested a default of CountPolicy.NONE will be used. This will result in no count being performed and no overhead incurred.

Parameters:

policy - The policy used to calculate total paged results

Returns:

This query request.

See Also:

QueryResponse.getTotalPagedResultsPolicy(), QueryResponse.getTotalPagedResults()

toJsonValue

JsonValue toJsonValue()

Description copied from interface: Request

Return a JsonValue representation of this request.

Specified by:

toJsonValue in interface Request

Returns:

this request as a JsonValue