public class RequestOptions
extends java.lang.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.
Modifier and Type | Field and Description |
---|---|
static java.lang.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 java.lang.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 and Description |
---|
RequestOptions() |
Modifier and Type | Method and Description |
---|---|
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. |
java.lang.String |
getDefaultXQueryVersion()
Get the default XQuery version string to use as the default for the request, if any.
|
java.math.BigInteger |
getEffectivePointInTime()
Returns the point-in-time timestamp value, if any, set in this object.
|
java.util.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.
|
java.lang.String |
getQueryLanguage() |
java.lang.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.
|
java.util.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(java.lang.String versionString)
Set the default XQuery version that should apply to this request.
|
void |
setEffectivePointInTime(java.math.BigInteger effectivePointInTime)
Set a point-in-time timestamp value.
|
void |
setLocale(java.util.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 |
setQueryLanguage(java.lang.String queryLanguage) |
void |
setRequestName(java.lang.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(java.util.TimeZone timeZone)
Set (or clear) the
TimeZone object to associate with this options instance. |
public static final int DEFAULT_MAX_AUTO_RETRY
public static final int DEFAULT_AUTO_RETRY_DELAY_MILLIS
public static final java.lang.String MAX_RETRY_SYSTEM_PROPERTY
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.public static final java.lang.String AUTO_RETRY_DELAY_SYSTEM_PROPERTY
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.public boolean getCacheResult()
Indicates whether the ResultSequence
should be cached when read from the server. The
default is true.
ResultSequence
should be cached, false if not.ResultSequence.isCached()
public void setCacheResult(boolean cacheResult)
ResultSequence
should be cached. The default is true.cacheResult
- Set to true to cause the ResultSequence
to be cached, false if it should
be streamable.public int getMaxAutoRetry()
MAX_RETRY_SYSTEM_PROPERTY
)
and a programmatic default (DEFAULT_MAX_AUTO_RETRY
).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.
maxAutoRetry
- The new max retry value to set. Set to zero for no retries. Set to -1 to apply the
default.public int getAutoRetryDelayMillis()
DEFAULT_AUTO_RETRY_DELAY_MILLIS
).public void setAutoRetryDelayMillis(int autoRetryDelayMillis)
autoRetryDelayMillis
- Milliseconds to delay (can be zero), -1 means use the default.public int getResultBufferSize()
ResultSequence
buffer size. A size of
zero indicates that the implementation default will be used.public void setResultBufferSize(int resultBufferSize)
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.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.public int getTimeoutMillis()
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.
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.setRequestTimeLimit(int)
public java.lang.String getRequestName()
A user-defined, name value sent with the Request
and logged on the server.
getRequestName()
public void setRequestName(java.lang.String requestName)
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.requestName
- A String or null to clear the name.java.lang.IllegalArgumentException
- If the string provided is not a valid request name.public java.util.Locale getLocale()
Locale
object associated with this instance.Locale
or null. A value of null indicates that the
JVM default locale should be associated with the request.public void setLocale(java.util.Locale locale)
Locale
object to associate with this options instance.locale
- A Locale
object or null. Setting the locale to null indicates
that the JVM default should be used.public java.util.TimeZone getTimeZone()
TimeZone
object associated with this instance.TimeZone
or null. A value of null indicates that the
JVM default timezone should be associated with the request.public void setTimeZone(java.util.TimeZone timeZone)
TimeZone
object to associate with this options instance.timeZone
- A TimeZone
object or null. Setting the timezone to null
indicates that the JVM default should be used.public java.math.BigInteger getEffectivePointInTime()
Request
it will affect the view of the content the query
will run against.BigInteger
object, or null.public void setEffectivePointInTime(java.math.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.
effectivePointInTime
- An instance of BigInteger
or null to clear the effective timestamp. Note
that a parameter with the value zero is equivalent to null.public java.lang.String getDefaultXQueryVersion()
public void setDefaultXQueryVersion(java.lang.String versionString)
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.public int getRequestTimeLimit()
setRequestTimeLimit(int)
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.
requestTimeLimit
- A number of seconds, or -1 for the XCC programmatic default, or zero for the app
server default.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.
others
- An array of RequestOption objects whose values will be collapsed into this oject.public java.lang.String getQueryLanguage()
public void setQueryLanguage(java.lang.String queryLanguage)
Copyright © 2022 MarkLogic Corporation. All Rights Reserved.
Complete online documentation for MarkLogic Server, XQuery and related components may be found at developer.marklogic.com