Package com.onwbp.adaptation

# Class Request

java.lang.Object
com.onwbp.adaptation.Request

public final class Request extends Object
Defines a specific request on a table.

A request is executed by calling the method `execute()`.

### Multi-threading

Note that this class is not synchronized.

### Performance

See Setting a fetch size on optimization with respect to the expected size of the `RequestResult` and the limitations when using PostgreSQL as the underlying database.

See Also:
  - `AdaptationTable.createRequest()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Map<SchemaNode,Adaptation>`
  `checkForbiddenNodes()`
  When the execution would fail and throw a `QueryPermissionException`, this method returns the forbidden fields and the dataset in which these are forbidden.
  `RequestResult`
  `execute()`
  Executes the request and returns the result.
  `int`
  `getFetchSize()`
  `Locale`
  `getLocale()`
  `RequestSortCriteria`
  `getSortCriteria()`
  `AdaptationFilter`
  `getSpecificFilter()`
  Returns the current filter, if any.
  `boolean`
  `isIncludeOcculting()`
  `boolean`
  `isSortedByRelevancy()`
  Returns whether the results of this request should be sorted by relevancy.
  `RequestPagination`
  `paginate()`
  Returns a new object to be used to paginate over the result of this request.
  `void`
  `setFetchSize(int rows)`
  Provides a hint to the underlying database as to the number of records to fetch at a time from the result of `executing` this request.
  `void`
  `setIncludeOcculting(boolean includeOcculting)`
  Sets whether or not the request must consider records in occulting mode.
  `void`
  `setLocale(Locale aLocale)`
  Sets a locale to the request.
  `void`
  `setOrderByPrimaryKey()`
  Specifies that the request result will be sorted by primary key in ascending order.
  `void`
  `setSession(Session aSession)`
  Sets the user session on the request.
  `void`
  `setSortCriteria(RequestSortCriteria aSortCriteria)`
  Specifies that the request result will be sorted according to the specified criteria.
  `void`
  `setSpecificFilter(AdaptationFilter aFilter)`
  Specifies that the request result will only include the records that satisfy the filter passed as an argument.
  `void`
  `setXPathFilter(XPathFilter anXPathFilter)`
  Specifies that the request result will only include the records which satisfy the specified XPath filter.
  `void`
  `setXPathFilter(String aPredicateExpression)`
  Specifies that the request result will only include the records which satisfy the specified XPath predicate.
  `void`
  `setXPathParameter(String aParameterName, Object aParameterValue)`
  For the current XPath filter, sets the value of the specified parameter.
  `void`
  `sortByRelevancy()`
  Specifies that the results of this request will be sorted according to their relevancy regarding the search criterion (most relevant first).
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Method Details

  - ### isIncludeOcculting

    public boolean isIncludeOcculting()
    See Also:
      - `setIncludeOcculting(boolean)`

  - ### setIncludeOcculting

    public void setIncludeOcculting(boolean includeOcculting)
    Sets whether or not the request must consider records in occulting mode.

    By default, these records are ignored.

  - ### getLocale

    public Locale getLocale()
    Since:
      5.5.0
    See Also:
      - `setLocale(Locale)`

  - ### setLocale

    public void setLocale(Locale aLocale)
    Sets a locale to the request. It may be needed if the request filter is locale-dependent, i.e. a predicate filter of the form `osd:label(./localized_field)='A'`.
    Since:
      5.5.0
    See Also:
      - `setSession(Session)`

  - ### setSession

    public void setSession(Session aSession)
    Sets the user session on the request. This activates the permission checks and sets the session locale.

    Applying the permissions checks will have the following effects:

    - the returned records will be filtered using the access rules on records if any;
    - a `QueryPermissionException` will be thrown on execution if at least one forbidden node is used in the request. Currently, this does not take into account record-dependent access rules set on fields.
    Since:
      5.5.0
    See Also:
      - `setLocale(Locale)`

  - ### getSortCriteria

    public RequestSortCriteria getSortCriteria()
    See Also:
      - `setSortCriteria(RequestSortCriteria)`

  - ### setOrderByPrimaryKey

    public void setOrderByPrimaryKey()
    Specifies that the request result will be sorted by primary key in ascending order.
    See Also:
      - `setSortCriteria(RequestSortCriteria)`

  - ### setSortCriteria

    public void setSortCriteria(RequestSortCriteria aSortCriteria)
    Specifies that the request result will be sorted according to the specified criteria.

    If this method is not called, the result will be ordered according to the primary key fields (ascending). If this method is called with a `null` sort criteria, the result will not be sorted in any particular order.

    Throws:
      `IllegalArgumentException` - if the specified sort is not consistent with the table structure.
    See Also:
      - `setOrderByPrimaryKey()`
      - `sortByRelevancy()`

  - ### sortByRelevancy

    public void sortByRelevancy()
    Specifies that the results of this request will be sorted according to their relevancy regarding the search criterion (most relevant first). This notion only makes sense for requests including a filter with text search. Requests which do not fulfill this condition will throw an error on `execute()` if they have specified this sort by relevancy. It is currently not possible to combine this special sort with additional sort criteria: this call will replace any pre-existing sort criteria.
    Since:
      6.0.0

  - ### isSortedByRelevancy

    public boolean isSortedByRelevancy()
    Returns whether the results of this request should be sorted by relevancy. Only requests including a filter with text search are likely to return `true`.
    Since:
      6.0.0
    See Also:
      - `sortByRelevancy()`

  - ### getSpecificFilter

    public AdaptationFilter getSpecificFilter()
    Returns the current filter, if any. If an XPath filter has been specified, returns its programmatic version.
    See Also:
      - `setSpecificFilter(AdaptationFilter)`
      - `setXPathFilter(XPathFilter)`

  - ### setSpecificFilter

    public void setSpecificFilter(AdaptationFilter aFilter)
    Specifies that the request result will only include the records that satisfy the filter passed as an argument.

    If not set, the value of this property is `null`, and no specific filtering will be performed.

    If a filter has been specified by means of a method `setXPathFilter`, it is replaced by the specified filter.

    See Also:
      - `setXPathFilter(XPathFilter)`

  - ### setXPathFilter

    public void setXPathFilter(String aPredicateExpression)
    Specifies that the request result will only include the records which satisfy the specified XPath predicate.

    This method is equivalent to:

         XPathFilter xpf = XPathFilter.newFilter(false, aPredicateExpression);
         this.setXPathFilter(xpf);

    Performance considerations: If the specified predicate must be often reused by multiple `Request` objects, it is recommended to use a cached filter. Parameterized expressions also help reuse.

    See Also:
      - `setXPathFilter(XPathFilter)`

  - ### setXPathFilter

    public void setXPathFilter(XPathFilter anXPathFilter)
    Specifies that the request result will only include the records which satisfy the specified XPath filter.

    If a filter has been specified by means of the method ``setSpecificFilter(AdaptationFilter)``, it is replaced by the specified XPath filter.

    It is recommended to use the XPath filter when the predicate must be applied more than once, with different values. It allows using parameters and avoiding parsing the same predicate expression each time it is used.

    Since:
      5.7.0
    See Also:
      - `setXPathParameter(String, Object)`
      - XPath supported syntax

  - ### setXPathParameter

    public void setXPathParameter(String aParameterName, Object aParameterValue)
    For the current XPath filter, sets the value of the specified parameter.

    For example, if the current filter is the XPath predicate `./lastName=$myName`, to set the parameter `myName` to 'Smith', the method must be invoked this way:

         aRequest.setXPathParameter("myName", "Smith");

    Parameters:
      `aParameterName` - name of the parameter
      `aParameterValue` - value of the parameter
    Throws:
      `IllegalArgumentException` - if one of the specified arguments is not defined or if the specified parameter name has basic inconsistencies.
      `IllegalStateException` - if no XPath filter has been specified.
    Since:
      5.7.0
    See Also:
      - `setXPathFilter(String)`
      - `Query.setParameter(int, java.lang.Object)`

  - ### getFetchSize

    public int getFetchSize()
    See Also:
      - `setFetchSize(int)`

  - ### setFetchSize

    public void setFetchSize(int rows)
    Provides a hint to the underlying database as to the number of records to fetch at a time from the result of `executing` this request. If the fetch size specified is '0', the underlying implementation determines the fetch size independently.
    Parameters:
      `rows` - the number of rows to fetch
    See Also:
      - `Query.setFetchSize(int)`
      - `Statement.setFetchSize(int)`

  - ### execute

    public RequestResult execute() throws IncompatibleChangeError, QueryPermissionException
    Executes the request and returns the result.

    Once this method has been called, it is mandatory to invoke the `RequestResult.close()` method on the returned object. Otherwise, this will fail to release some system resources.

    Throws:
      `QueryPermissionException` - if a session is provided and at least one forbidden node is used in the request.
      `IncompatibleChangeError`
    See Also:
      - ``

  - ### checkForbiddenNodes

    public Map<SchemaNode,Adaptation> checkForbiddenNodes()
    When the execution would fail and throw a `QueryPermissionException`, this method returns the forbidden fields and the dataset in which these are forbidden. Otherwise, returns an empty map.
    Since:
      6.0.0

  - ### paginate

    public RequestPagination paginate()
    Returns a new object to be used to paginate over the result of this request.
    Since:
      5.8.0

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`