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.
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	getResultBufferSize() The currently set (or default if never set) ResultSequence buffer size.
int	getTimeoutMillis() Get the 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	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	setResultBufferSize(int resultBufferSize) Set the suggested ResultSequence buffer size for this execution.
void	setTimeoutMillis(int timeoutMillis) Set the timeout value (in milliseconds) that should be applied to query execution.
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 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 should be used.

setTimeoutMillis

public void setTimeoutMillis(int timeoutMillis)

Set the timeout value (in milliseconds) that should be applied to query execution. If a response is not received within this time interval, the query will be terminated and an exception will be thrown. A value of zero indicates no timeout.

This is a hint to the implementation. It may not always be possible to reliably timeout a request within the suggested time. Server settings may also interact with or override this value.

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 for server reply before abandoning the query and throwing an exception. 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.

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.

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.