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 and Description
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()
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) If the argument is true, this method specifies that the request result will include 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(String aPredicateExpression) Specifies that the request result will only include the records which satisfy the specified XPath predicate.
void	setXPathFilter(XPathFilter anXPathFilter) Specifies that the request result will only include the records which satisfy the specified XPath filter.
void	setXPathParameter(String aParameterName, Object aParameterValue) For the current XPath filter, sets the value of the specified parameter.
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

isIncludeOcculting

public boolean isIncludeOcculting()

See Also:

setIncludeOcculting(boolean)

setIncludeOcculting

public void setIncludeOcculting(boolean includeOcculting)

If the argument is true, this method specifies that the request result will include records in occulting mode.

If the argument is false, records in occulting mode are not included in the result. If the property is not set, it is considered to be false.

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 rules on the result and sets the session locale.

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 default sort order is undefined, in which case the results will be sorted according to the order of whichever index is selected for computing the request. If no filter is specified, the result will be ordered according to the primary key fields (ascending).

Throws:

IllegalArgumentException - if the specified sort is not consistent with the table structure.

See Also:

setOrderByPrimaryKey(), AdaptationTable.createRequestResult(String, RequestSortCriteria)

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)

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.

See Setting a fetch size for the limitations when using PostgreSQL as the underlying database.

Parameters:

rows - the number of rows to fetch

See Also:

Statement.setFetchSize(int)

execute

public RequestResult execute()
                      throws IncompatibleChangeError

Executes the request and returns the result.

Throws:

IncompatibleChangeError

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