com.marklogic.xcc
Class RequestOptions

java.lang.Object
  com.marklogic.xcc.RequestOptions

public class RequestOptions
extends Object

This class represents options to apply to execution of a query. RequestOptions may be set on both Request and on Session objects. Options set on Request take priority. The effective options applied to a request are a blend of of the two objects with defaults applied to values not explicitly set. Use the method Request.getEffectiveOptions() to determine the actual values that will be applied to a given request.

Field Summary

static String	AUTO_RETRY_DELAY_SYSTEM_PROPERTY The system property name (xcc.request.retries.delay) which, if set, specifies the default delay (in milliseconds) between automatic request retries.
static int	DEFAULT_AUTO_RETRY_DELAY_MILLIS Default delay (in milliseconds) between automatic query retries (value: 100)
static int	DEFAULT_MAX_AUTO_RETRY Default max retry attempts on a request or content insertion (value: 4)
static String	MAX_RETRY_SYSTEM_PROPERTY The system property name (xcc.request.retries.max) which, if set, specifies the default maximum number of automatic retries.

Constructor Summary

RequestOptions()

Method Summary

void	applyEffectiveValues(RequestOptions[] others) Set the option values of this object to the effective values obtained by merging each of the RequestOption objects in the array.
int	getAutoRetryDelayMillis() The number of milliseconds to delay between each automatic query retry attempt.
boolean	getCacheResult() Indicates whether the ResultSequence should be cached when read from the server.
String	getDefaultXQueryVersion() Get the default XQuery version string to use as the default for the request, if any.
BigInteger	getEffectivePointInTime() Returns the point-in-time timestamp value, if any, set in this object.
Locale	getLocale() The (possibly null) Locale object associated with this instance.
int	getMaxAutoRetry() The maximum number of times a retryable request will be automatically retried before throwing an exception.
String	getRequestName() A user-defined, name value sent with the Request and logged on the server.
int	getRequestTimeLimit() Get the "soft" request time limit (in seconds) to apply to the submitted request.
int	getResultBufferSize() The currently set (or default if never set) ResultSequence buffer size.
int	getTimeoutMillis() Get the read timeout value (in milliseconds) for this options object.
TimeZone	getTimeZone() The (possibly null) TimeZone object associated with this instance.
void	setAutoRetryDelayMillis(int autoRetryDelayMillis) Set the time to delay (in milliseconds) between automatic query retries.
void	setCacheResult(boolean cacheResult) Indicates whether the ResultSequence should be cached.
void	setDefaultXQueryVersion(String versionString) Set the default XQuery version that should apply to this request.
void	setEffectivePointInTime(BigInteger effectivePointInTime) Set a point-in-time timestamp value.
void	setLocale(Locale locale) Set (or clear) the Locale object to associate with this options instance.
void	setMaxAutoRetry(int maxAutoRetry) The maximum number of times a retryable request will be automatically retried before throwing an exception.
void	setRequestName(String requestName) Set a user-defined, name value to be associated with the Request.
void	setRequestTimeLimit(int requestTimeLimit) Set the "soft" time limit (in seconds) to apply to the submitted request.
void	setResultBufferSize(int resultBufferSize) Set the suggested ResultSequence buffer size for this execution.
void	setTimeoutMillis(int timeoutMillis) Set the timeout value, in milliseconds, for the low-level connection.
void	setTimeZone(TimeZone timeZone) Set (or clear) the TimeZone object to associate with this options instance.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MAX_AUTO_RETRY

public static final int DEFAULT_MAX_AUTO_RETRY

Default max retry attempts on a request or content insertion (value: 4)

See Also:

Constant Field Values

DEFAULT_AUTO_RETRY_DELAY_MILLIS

public static final int DEFAULT_AUTO_RETRY_DELAY_MILLIS

Default delay (in milliseconds) between automatic query retries (value: 100)

See Also:

Constant Field Values

MAX_RETRY_SYSTEM_PROPERTY

public static final String MAX_RETRY_SYSTEM_PROPERTY

The system property name (xcc.request.retries.max) which, if set, specifies the default maximum number of automatic retries. If not set, the programatic default is used ( DEFAULT_MAX_AUTO_RETRY) as the default.

See Also:

Constant Field Values

AUTO_RETRY_DELAY_SYSTEM_PROPERTY

public static final String AUTO_RETRY_DELAY_SYSTEM_PROPERTY

The system property name (xcc.request.retries.delay) which, if set, specifies the default delay (in milliseconds) between automatic request retries. If not set, the programatic default is used (DEFAULT_AUTO_RETRY_DELAY_MILLIS) as the default.

See Also:

Constant Field Values

Constructor Detail

RequestOptions

public RequestOptions()

Method Detail

getCacheResult

public boolean getCacheResult()

Indicates whether the ResultSequence should be cached when read from the server. The default is true.

Returns:

true if the ResultSequence should be cached, false if not.

See Also:

ResultSequence.isCached()

setCacheResult

public void setCacheResult(boolean cacheResult)

Indicates whether the ResultSequence should be cached. The default is true.

Parameters:

cacheResult - Set to true to cause the ResultSequence to be cached, false if it should be streamable.

getMaxAutoRetry

public int getMaxAutoRetry()

The maximum number of times a retryable request will be automatically retried before throwing an exception. A return value of -1 indicates that a default value will be used. The default is determined by checking for a system property setting (MAX_RETRY_SYSTEM_PROPERTY) and a programmatic default (DEFAULT_MAX_AUTO_RETRY).

Returns:

The currently set max retry value, or -1. The value -1 indicates that a default value should be used.

setMaxAutoRetry

public void setMaxAutoRetry(int maxAutoRetry)

The maximum number of times a retryable request will be automatically retried before throwing an exception. Setting a value of -1 indicates that the default value should be used. A value of zero indicates that no retries should be attempted.

Note that this is the number of retries, not the total number of tries. Setting this value to 4, for example, means that the request will be attempted 5 times before giving up.

Parameters:

maxAutoRetry - The new max retry value to set. Set to zero for no retries. Set to -1 to apply the default.

getAutoRetryDelayMillis

public int getAutoRetryDelayMillis()

The number of milliseconds to delay between each automatic query retry attempt.

Returns:

The number of milliseconds to delay. Zero means no delay, -1 means use the default ( DEFAULT_AUTO_RETRY_DELAY_MILLIS).

setAutoRetryDelayMillis

public void setAutoRetryDelayMillis(int autoRetryDelayMillis)

Set the time to delay (in milliseconds) between automatic query retries.

Parameters:

autoRetryDelayMillis - Milliseconds to delay (can be zero), -1 means use the default.

getResultBufferSize

public int getResultBufferSize()

The currently set (or default if never set) ResultSequence buffer size. A size of zero indicates that the implementation default will be used.

Returns:

The currently set buffer size value.

setResultBufferSize

public void setResultBufferSize(int resultBufferSize)

Set the suggested ResultSequence buffer size for this execution. This is a hint to the implementation. If the requested size is not reasonable (too big or too small) or not appropriate for the result, this hint may be ignored or constrained. In most cases, the default setting should work well.

Parameters:

resultBufferSize - The suggested buffer size to use when processing the result of the execution. A value of zero means that the implementation should use programmatic defaults.

getTimeoutMillis

public int getTimeoutMillis()

Get the read timeout value (in milliseconds) for this options object.

Returns:

The timeout setting (in milliseconds). A value of zero indicates no timeout. A value of -1 indicates that the default is being used.

setTimeoutMillis

public void setTimeoutMillis(int timeoutMillis)

Set the timeout value, in milliseconds, for the low-level connection. This is almost certainly not what you want. You probably want the setRequestTimeLimit(int) option to set a limit on the amount of time a request is allowed to run.

This option sets a read timeout on the low-level connection. It is here for historical reasons but should not be used by most users. Connections are managed automatically by XCC and low-level reads do not necessarily correspond to calls you make to the XCC API.

If query results are cached (the default, see setCacheResult(boolean)), then this option will usually have no effect because all data is read immediately. For non-cached result sequences, this timeout may come into play. XCC prebuffers the data it reads which means that low-level reads can happen at unpredictable times.

It is generally preferrable to set timeout values on the XBDC appserver in the admin UI to control conection timeouts. Setting this to a value other than zero or -1 can result in a small performance hit. Don't use it unless you really, really know what you're doing.

The default value for this setting is -1, which indicates that a default value should be used. The default is usually zero. A value of zero indicates no timeout.

Parameters:

timeoutMillis - The number of milliseconds to wait before timing out a low-level socket read. Zero explicitly indicates no timeout, -1 indicates the default should be used (which is typically zero, but could have been set on the Session to some other value.

See Also:

setRequestTimeLimit(int)

getRequestName

public String getRequestName()

A user-defined, name value sent with the Request and logged on the server.

Returns:

The currently set value, or null.

See Also:

getRequestName()

setRequestName

public void setRequestName(String requestName)

Set a user-defined, name value to be associated with the Request. The value provided must be an alphanumeric string (letters and numbers only, must start with a letter). It will be logged as the HTTP Referer header in the access log and may be set as the name of the request while running in the server. This name may be visible in the MarkLogic Server admin interface.

Parameters:

requestName - A String or null to clear the name.

Throws:

IllegalArgumentException - If the string provided is not a valid request name.

getLocale

public Locale getLocale()

The (possibly null) Locale object associated with this instance.

Returns:

An instance of Locale or null. A value of null indicates that the JVM default locale should be associated with the request.

setLocale

public void setLocale(Locale locale)

Set (or clear) the Locale object to associate with this options instance.

Parameters:

locale - A Locale object or null. Setting the locale to null indicates that the JVM default should be used.

getTimeZone

public TimeZone getTimeZone()

The (possibly null) TimeZone object associated with this instance.

Returns:

An instance of TimeZone or null. A value of null indicates that the JVM default timezone should be associated with the request.

setTimeZone

public void setTimeZone(TimeZone timeZone)

Set (or clear) the TimeZone object to associate with this options instance.

Parameters:

timeZone - A TimeZone object or null. Setting the timezone to null indicates that the JVM default should be used.

getEffectivePointInTime

public BigInteger getEffectivePointInTime()

Returns the point-in-time timestamp value, if any, set in this object. If a point-in-time value is associated with a Request it will affect the view of the content the query will run against.

Returns:

A BigInteger object, or null.

setEffectivePointInTime

public void setEffectivePointInTime(BigInteger effectivePointInTime)

Set a point-in-time timestamp value. When a point-in-time timestamp is associated with a Request it determines the visibility of content that a query runs against.

The latest point-in-time timestamp may be obtained from the server by invoking Session.getCurrentServerPointInTime().

When a non-zero point-in-time is in effect, only read-only requests are allowed. Updates, which modify the state of the contentbase, are not allowed. Point-in-time queries are effectively running in the past and updates are always applied to the current state of the contentbase.

Note that some queries with an effective point-in-time may throw an XQueryException if deleted fragments needed to recreate the effective state have been dropped by a subsequent merge. The MarkLogic Server administrative interface contains controls to retain fragments newer than a specified timestamp.

Parameters:

effectivePointInTime - An instance of BigInteger or null to clear the effective timestamp. Note that a parameter with the value zero is equivalent to null.

getDefaultXQueryVersion

public String getDefaultXQueryVersion()

Get the default XQuery version string to use as the default for the request, if any.

Returns:

An XQuery version String, or null.

Since:

4.0

setDefaultXQueryVersion

public void setDefaultXQueryVersion(String versionString)

Set the default XQuery version that should apply to this request. Setting a default determines which version of XQuery to use in the absence of an explicit declaration within the code. If this value is never set, or if it's set to null, the default XQuery version selected for the XDBC app server will be used.

Parameters:

versionString - An XQuery version String, or null. Valid XQuery version strings are "0.9-ml", "1.0-ml" and "1.0". Setting to null defaults to the app server configuration.

Since:

4.0

getRequestTimeLimit

public int getRequestTimeLimit()

Get the "soft" request time limit (in seconds) to apply to the submitted request. The default value is -1, which means to apply the programmatic default.

Returns:

A number of seconds, or -1.

See Also:

setRequestTimeLimit(int)

setRequestTimeLimit

public void setRequestTimeLimit(int requestTimeLimit)

Set the "soft" time limit (in seconds) to apply to the submitted request. Passing -1 means use the default, possibly inherited from a Session object. A value of zero indicates that the default value configured on the appserver should be used. Any other positive number is interpreted as a number of seconds.

The request soft time limit may be set to any value less than or equal to the hard limit (max-time-limit) set on the app server. The setting will apply only to the submitted request, it does not affect any permanent app server settings.

Parameters:

requestTimeLimit - A number of seconds, or -1 for the XCC programmatic default, or zero for the app server default.

applyEffectiveValues

public void applyEffectiveValues(RequestOptions[] others)

Set the option values of this object to the effective values obtained by merging each of the RequestOption objects in the array. Last, non-default value wins (starting at index 0). Any remaining values that indicate a default are replaced with the appropriate value.

This method is primarily intended for internal use. In general, you should instantiate a new RequestOptions object and set only those properties you want to explicitly override.

Parameters:

others - An array of RequestOption objects whose values will be collapsed into this oject.