Request (MarkLogic XML Content Connector For Java (XCC/J) v11.4)

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.

Interface Request

Method Summary

Method Detail

getSession

setOptions

getOptions

getEffectiveOptions

setVariable

setNewVariable

setNewVariables

setNewVariable

setNewVariables

setNewVariable

setNewVariables

setNewStringVariable

setNewStringVariable

setNewIntegerVariable

setNewIntegerVariable

clearVariable

clearVariables

getVariables

getPosition

setPosition

getCount

setCount