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

public 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

public void setOptions(RequestOptions options)

Associate the given RequestOptions object with this Request.

Parameters:

options - An RequestOptions instance or null to use default values.

getOptions

public RequestOptions getOptions()

Returns the currently set RequestOptions object.

Returns:

An instance of RequestOptions or null if none is currently in effect.

getEffectiveOptions

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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 XSString

setNewIntegerVariable

public 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

public 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

public void clearVariables()

Remove any variables set in this Request.

getVariables

public XdmVariable[] getVariables()

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

Returns:

An array of XdmVariable objects.