com.marklogic.xcc

## Interface Request

- All Known Subinterfaces:
    AdhocQuery, ModuleInvoke, ModuleSpawn

      public interface Request

  Base Request interface that contains methods common to all requests. Methods defined here manage request options and variable binding.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearVariable(XdmVariable variable)` Remove the given variable from this Request context.
    `void` | `clearVariables()` Remove any variables set in this Request.
    `long` | `getCount()` Get count of result items for this request.
    `RequestOptions` | `getEffectiveOptions()` Returns a `RequestOptions` instance that reflects the execution options that will be applied to this request.
    `RequestOptions` | `getOptions()` Returns the currently set `RequestOptions` object.
    `long` | `getPosition()` Get starting position of results for this request.
    `Session` | `getSession()` The session which created this Request.
    `XdmVariable[]` | `getVariables()` Return an array (possibly zero length) of all the `XdmVariable` objects currently set on this Request.
    `void` | `setCount(long count)` Set count of result items for this request.
    `XdmVariable` | `setNewIntegerVariable(java.lang.String localname, long value)` Convenience method that creates a new `XSInteger`, binds it to this Request and then returns the new `XSInteger` instance.
    `XdmVariable` | `setNewIntegerVariable(java.lang.String namespace, java.lang.String localname, long value)` Convenience method that creates a new `XSInteger`, binds it to this Request and then returns the new `XSInteger` instance.
    `XdmVariable` | `setNewStringVariable(java.lang.String localname, java.lang.String value)` Convenience method that creates a new `XSString`, binds it to this Request and then returns the new `XSString` instance.
    `XdmVariable` | `setNewStringVariable(java.lang.String namespace, java.lang.String localname, java.lang.String value)` Convenience method that creates a new `XSString`, binds it to this Request and then returns the new `XSString` instance.
    `XdmVariable` | `setNewVariable(java.lang.String namespace, java.lang.String localname, ValueType type, java.lang.Object value)` Convenience method that creates a new `XdmVariable`, binds it to this Request and then returns the new `XdmVariable` object.
    `XdmVariable` | `setNewVariable(java.lang.String localname, ValueType type, java.lang.Object value)` Convenience method that creates a new `XdmVariable`, binds it to this Request and then returns the new `XdmVariable`.
    `XdmVariable` | `setNewVariable(XName xname, XdmValue value)` Convenience method that creates a new `XdmVariable`, binds it to this Request and then returns the new `XdmVariable` object.
    `void` | `setNewVariables(java.lang.String namespace, java.lang.String localname, ValueType type, java.lang.Object[] values)` Creates a sequence `XdmVariable` from the input values and binds it to this Request.
    `void` | `setNewVariables(java.lang.String localname, ValueType type, java.lang.Object[] values)` Creates a sequence `XdmVariable` from the input values and binds it to this Request.
    `void` | `setNewVariables(XName xname, XdmValue[] values)` Creates a sequence `XdmVariable` from the input values and binds it to this Request.
    `void` | `setOptions(RequestOptions options)` Associate the given `RequestOptions` object with this Request.
    `void` | `setPosition(long position)` Set starting position of results for this request.
    `void` | `setVariable(XdmVariable variable)` Associate the given `XdmVariable` with this Request.

- - ### Method Detail

    - #### getSession

          Session getSession()

      The session which created this Request. Request objects are created by factory methods on `Session` and their implementations are interdependent.
      Returns:
        A `Session` reference.

    - #### setOptions

          void setOptions(RequestOptions options)

      Associate the given `RequestOptions` object with this Request.
      Parameters:
        `options` - An `RequestOptions` instance or null to use default values.

    - #### getOptions

          RequestOptions getOptions()

      Returns the currently set `RequestOptions` object.
      Returns:
        An instance of `RequestOptions` or null if none is currently in effect.

    - #### getEffectiveOptions

          RequestOptions getEffectiveOptions()

      Returns a `RequestOptions` instance that reflects the execution options that will be applied to this request. This may be a blend of the option values set on the Request and those set on the `Session`. This method will always return a newly created, non-null result.

      The object returned is NOT the `RequestOptions` object associated with either the Request or the `Session`. Making changes to the returned `RequestOptions` object will not affect subsequent submissions of this Request.

      Although it's possible to modify and pass the returned object back to `setOptions(RequestOptions)`, this is not recommended. In general, you should create your own instance of `RequestOptions` and set only those options you explictly want to override. When submitted, the options set on the Request are merged with those, if any, set for the `Session`.

      This method mainly used internally. It can be used to determine which values will be submitted with a request. Most client code will not need this method.

      Returns:
        A newly created instance of `RequestOptions`.

    - #### setVariable

          void setVariable(XdmVariable variable)

      Associate the given `XdmVariable` with this Request. If another variable with the same name is already set, it is replaced. When an invocation of `Session.submitRequest(Request)` is made, all currently set variables are sent with the request and defined as XQuery external variables when the query runs in the server.
      Parameters:
        `variable` - A `XdmVariable` instance to be associated with this Request. If another variable with the same name ( `XName`) is already bound, it will be replaced with this one. Note that `XName` instances with the same namespace/local name values are considered to be equal.
      Throws:
        `UnimplementedFeatureException` - If the variable is not a type that can be passed with the Request, e.g. XdmSequence is not a supported type for external variables.

    - #### setNewVariable

          XdmVariable setNewVariable(XName xname,
                                     XdmValue value)

      Convenience method that creates a new `XdmVariable`, binds it to this Request and then returns the new `XdmVariable` object. This method is equivalent to:

      ``

           XdmVariable temp = ValueFactory.newVariable (xname, value);
           request.setVariable (temp);
           return temp;

      Parameters:
        `xname` - An instance of `XName`, which defines a namespace (optional) and a localname.
        `value` - An instance of `XdmValue` which will be the value of the `XdmVariable` .
      Returns:
        The newly construct `XdmVariable` instance.

    - #### setNewVariables

          void setNewVariables(XName xname,
                               XdmValue[] values)

      Creates a sequence `XdmVariable` from the input values and binds it to this Request.

      Parameters:
        `xname` - An instance of `XName`, which defines a namespace (optional) and a localname.
        `values` - An array of `XdmValue` which will be the values in the sequence..

    - #### setNewVariable

          XdmVariable setNewVariable(java.lang.String namespace,
                                     java.lang.String localname,
                                     ValueType type,
                                     java.lang.Object value)

      Convenience method that creates a new `XdmVariable`, binds it to this Request and then returns the new `XdmVariable` object. This method is equivalent to:

      ``

           XdmVariable temp = ValueFactory.newVariable (
               new XName (namespace, localname),
               ValueFactory.newValue (type, value));
           request.setVariable (temp);
           return temp;

      Parameters:
        `namespace` - A namespace String, or null for the default namespace.
        `localname` - The local name as a String.
        `type` - An instance of `ValueType` that indicates which specific subclass of `XdmValue` to instantiate.
        `value` - An object that contains the value. The concrete type that should be passed is dependent on the `ValueType` instance provided as the "type" parameter.
      Returns:
        An XdmVariable instance.

    - #### setNewVariables

          void setNewVariables(java.lang.String namespace,
                               java.lang.String localname,
                               ValueType type,
                               java.lang.Object[] values)

      Creates a sequence `XdmVariable` from the input values and binds it to this Request.

      Parameters:
        `namespace` - A namespace String, or null for the default namespace.
        `localname` - The local name as a String.
        `type` - An instance of `ValueType` that indicates specific subclass of `XdmValue` to instantiate in the sequence.
        `values` - An array of objects that contains the value. The concrete type that should be passed is dependent on the `ValueType` instance provided as the "type" parameter.

    - #### setNewVariable

          XdmVariable setNewVariable(java.lang.String localname,
                                     ValueType type,
                                     java.lang.Object value)

      Convenience method that creates a new `XdmVariable`, binds it to this Request and then returns the new `XdmVariable`. This method is equivalent to:

      ``

           XdmVariable temp = ValueFactory.newVariable (
               new XName (null, localname),
               ValueFactory.newValue (type, value));
           request.setVariable (temp);
           return temp;

      Parameters:
        `localname` - The local name as a String.
        `type` - An instance of `ValueType` that indicates which specific subclass of `XdmValue` to instantiate.
        `value` - An object that contains the value. The concrete type that should be passed is dependent on the `ValueType` instance provided as the "type" parameter.
      Returns:
        An XdmVariable instance.

    - #### setNewVariables

          void setNewVariables(java.lang.String localname,
                               ValueType type,
                               java.lang.Object[] values)

      Creates a sequence `XdmVariable` from the input values and binds it to this Request.

      Parameters:
        `localname` - The local name as a String.
        `type` - An instance of `ValueType` that indicates specific subclass of `XdmValue` to instantiate in the sequence.
        `values` - An array of objects that contains the values. The concrete type that should be passed is dependent on the `ValueType` instance provided as the "type" parameter.

    - #### setNewStringVariable

          XdmVariable setNewStringVariable(java.lang.String namespace,
                                           java.lang.String localname,
                                           java.lang.String value)

      Convenience method that creates a new `XSString`, binds it to this Request and then returns the new `XSString` instance. This method is equivalent to:

      ``

           XdmVariable temp = ValueFactory.newVariable (
               new XName (namespace, localname),
               ValueFactory.newValue (ValueType.XS_STRING, value));
           request.setVariable (temp);
           return temp;

      Parameters:
        `namespace` - A namespace String, or null for the default namespace.
        `localname` - The local name as a String.
        `value` - A String that contains the value.
      Returns:
        An instance of `XSString`

    - #### setNewStringVariable

          XdmVariable setNewStringVariable(java.lang.String localname,
                                           java.lang.String value)

      Convenience method that creates a new `XSString`, binds it to this Request and then returns the new `XSString` instance. This method is equivalent to:

      ``

          request.setNewStringVariable (null, localname, value)

      Parameters:
        `localname` - The local name as a String.
        `value` - A String that contains the value.
      Returns:
        An instance of `XSString`
      See Also:
        `setNewStringVariable(String, String, String)`

    - #### setNewIntegerVariable

          XdmVariable setNewIntegerVariable(java.lang.String namespace,
                                            java.lang.String localname,
                                            long value)

      Convenience method that creates a new `XSInteger`, binds it to this Request and then returns the new `XSInteger` instance. This method is equivalent to:

      ``

           XdmVariable temp = ValueFactory.newVariable (
               new XName (namespace, localname),
               ValueFactory.newValue (ValueType.XS_INTEGER, value));
           request.setVariable (temp);
           return temp;

      Parameters:
        `namespace` - A namespace String, or null for the default namespace.
        `localname` - The local name as a String.
        `value` - A long that contains the value. Note that XQuery integers may contain much larger values that Java ints. If you need to specify a value larger than can be expressed by a long, use `ValueFactory.newValue(com.marklogic.xcc.types.ValueType, Object)` and pass a `BigInteger` object as the value.
      Returns:
        An instance of `XSInteger`

    - #### setNewIntegerVariable

          XdmVariable setNewIntegerVariable(java.lang.String localname,
                                            long value)

      Convenience method that creates a new `XSInteger`, binds it to this Request and then returns the new `XSInteger` instance. This method is equivalent to:

      ``

          request.setNewIntegerVariable (null, localname, value)

      Parameters:
        `localname` - The local name as a String.
        `value` - A long that contains the value.
      Returns:
        An instance of `XSInteger`
      See Also:
        `setNewIntegerVariable(String, String, long)`

    - #### clearVariable

          void clearVariable(XdmVariable variable)

      Remove the given variable from this Request context. The variable and its value are still valid and may be reassociated with the session by passing it to `setVariable(com.marklogic.xcc.types.XdmVariable)`.
      Parameters:
        `variable` - A `XdmVariable` instance to be diassociated from this Request.

    - #### clearVariables

          void clearVariables()

      Remove any variables set in this Request.

    - #### getVariables

          XdmVariable[] getVariables()

      Return an array (possibly zero length) of all the `XdmVariable` objects currently set on this Request.
      Returns:
        An array of `XdmVariable` objects.

    - #### getPosition

          long getPosition()

      Get starting position of results for this request.
      Returns:
        starting position of results for this request.

    - #### setPosition

          void setPosition(long position)

      Set starting position of results for this request.
      Parameters:
        `position` - starting position.

    - #### getCount

          long getCount()

      Get count of result items for this request.
      Returns:
        count

    - #### setCount

          void setCount(long count)

      Set count of result items for this request.
      Parameters:
        `count` - count.

Copyright © 2025 MarkLogic Corporation

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