Overview | Package | Class | Tree | Deprecated | Index | Help
| XCC/J 4.2-9
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
`void` | `clearVariable(XdmVariable variable)` Remove the given variable from this Request context.
`void` | `clearVariables()` Remove any variables set in 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.
`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.
`XdmVariable` | `setNewIntegerVariable(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(String namespace, 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(String localname, String value)` Convenience method that creates a new `XSString`, binds it to this Request and then returns the new `XSString` instance.
`XdmVariable` | `setNewStringVariable(String namespace, String localname, String value)` Convenience method that creates a new `XSString`, binds it to this Request and then returns the new `XSString` instance.
`XdmVariable` | `setNewVariable(String namespace, String localname, ValueType type, Object value)` Convenience method that creates a new `XdmVariable`, binds it to this Request and then returns the new `XdmVariable` object.
`XdmVariable` | `setNewVariable(String localname, ValueType type, 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` | `setOptions(RequestOptions options)` Associate the given `RequestOptions` object with 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. Some server versions only support setting variables that are atomic (no nodes or sequences).

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

### setNewVariable

    XdmVariable setNewVariable(String namespace,
                               String localname,
                               ValueType type,
                               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.

### setNewVariable

    XdmVariable setNewVariable(String localname,
                               ValueType type,
                               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.

### setNewStringVariable

    XdmVariable setNewStringVariable(String namespace,
                                     String localname,
                                     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(String localname,
                                     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(String namespace,
                                      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(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.

Overview | Package | Class | Tree | Deprecated | Index | Help
| XCC/J 4.2-9
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2003-2012 MarkLogic Corporation, All Rights Reserved.

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