com.marklogic.xcc

## Class RequestOptions

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

-     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.

- - ### Field Summary

    Fields
    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 Summary

    Constructors
    Constructor and Description
    `RequestOptions()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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.

    - ### 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 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. 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 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. 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 java.lang.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(java.lang.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:
        `java.lang.IllegalArgumentException` - If the string provided is not a valid request name.

    - #### getLocale

          public java.util.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(java.util.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 java.util.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(java.util.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 java.math.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(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.

      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 java.lang.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(java.lang.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.

    - #### getQueryLanguage

          public java.lang.String getQueryLanguage()

    - #### setQueryLanguage

          public void setQueryLanguage(java.lang.String queryLanguage)

Copyright © 2025 MarkLogic Corporation

Complete online documentation for MarkLogic Server, XQuery and related components may be found at docs.progress.com