public interface ServerEvaluationCall
ServerEvaluationCall uses a fluent builder-style API to collect the parameters
for a server-side xquery
or javascript
eval or
invoke (modulePath
) call. ServerEvaluationCall also
conveniently has the eval* methods which execute those calls and return the
results. You must call one and only one of the following methods: xquery,
javascript, or modulePath. The xquery
and javascript methods initialize this call for server-side eval and accept
source code as a String or a TextWriteHandle (in case you are streaming the
source code from the file system, a URL, or other source that is most easily
accessed via io handles). The modulePath method initializes this call for server-
side invoke given the path to a module previously installed on the server.
String javascript = "'hello world'";
String response = client.newServerEval()
.javascript(javascript)
.evalAs(String.class);
assertEquals("hello world", response);
or in xquery:
String xquery = "'hello world'";
String response = client.newServerEval()
.xquery(xquery)
.evalAs(String.class);
assertEquals("hello world", response);
Variables can be added with the addVariable methods.
addVariable(String, AbstractWriteHandle)
allows you to pass complex JSON or XML values directly from io handles.
addVariableAs(String, Object)
follows the
shortcut pattern which maps objects by type to the appropriate handle.
For simpler atomic values, convenience addVariable methods are provided for
String, Number, and Boolean types.
String javascript = "var planet;'hello solar system from ' + planet";
String response = client.newServerEval()
.javascript(javascript)
.addVariable("planet", "Mars")
.evalAs(String.class);
assertEquals( "hello solar system from Mars", response);
or in xquery:
String xquery = "declare variable $planet external;'hello solar system from ' || $planet";
String response = client.newServerEval()
.xquery(xquery)
.addVariable("planet", "Mars")
.evalAs(String.class);
assertEquals( "hello solar system from Mars", response);
Each call can be executed within a transaction
, within a
particular database
,
and with particular namespaces
available for expansion
of prefixed variable names.
Each call can be executed with only one expected response of a particular type
or handle type
. Or calls can be
executed with multiple responses expected
. Calls that expect
only one response but need to stream the response should still use
eval()
and EvalResultIterator
so the response isn't closed
before the streaming begins.
NOTE: EvalResultIterator MUST BE CLOSED. If you call eval()
don't forget to call close() on the returned EvalResultIterator to free up the
underlying resources.
Modifier and Type | Method and Description |
---|---|
ServerEvaluationCall |
addNamespace(java.lang.String prefix,
java.lang.String namespaceURI)
Add a single namespace prefix-to-uri mapping to the namespace context.
|
ServerEvaluationCall |
addVariable(java.lang.String name,
AbstractWriteHandle value)
Set a variable name-value pair to pass to the code executing server-side.
|
ServerEvaluationCall |
addVariable(java.lang.String name,
java.lang.Boolean value)
Set a variable name-value pair to pass to the code executing server-side.
|
ServerEvaluationCall |
addVariable(java.lang.String name,
java.lang.Number value)
Set a variable name-value pair to pass to the code executing server-side.
|
ServerEvaluationCall |
addVariable(java.lang.String name,
java.lang.String value)
Set a variable name-value pair to pass to the code executing server-side.
|
ServerEvaluationCall |
addVariableAs(java.lang.String name,
java.lang.Object value)
Convenience method to set a variable of a type mapped to an io handle.
|
EvalResultIterator |
eval()
Provides all results returned by the server-side eval or invoke call.
|
<H extends AbstractReadHandle> |
eval(H responseHandle)
Provides the single result of the server-side eval or invoke call, wrapped in an io
handle.
|
<T> T |
evalAs(java.lang.Class<T> responseType)
Conveneince method to get the response serialized to a particular type by an io handle.
|
ServerEvaluationCall |
javascript(java.lang.String javascript)
Initialize this server-side eval with javascript-syntax source code.
|
ServerEvaluationCall |
javascript(TextWriteHandle javascript)
Initialize this server-side eval call with javascript-syntax source code.
|
ServerEvaluationCall |
modulePath(java.lang.String modulePath)
Initialize this server-side invoke call with a path to the module to invoke.
|
ServerEvaluationCall |
namespaceContext(EditableNamespaceContext namespaces)
Initialize this call with namespaces so variables with prefixes can be sent with
their prefixes translated to uris that will match the uris in the code to be
executed on the server.
|
ServerEvaluationCall |
transaction(Transaction transaction)
Initialize this call with a transaction under which server-side execution should occur.
|
ServerEvaluationCall |
xquery(java.lang.String xquery)
Initialize this server-side eval with xquery-syntax source code.
|
ServerEvaluationCall |
xquery(TextWriteHandle xquery)
Initialize this server-side eval with xquery-syntax source code.
|
ServerEvaluationCall xquery(java.lang.String xquery)
xquery
- the xquery-syntax source code to eval on the serverServerEvaluationCall xquery(TextWriteHandle xquery)
xquery
- a handle containing the xquery-syntax source code to eval on the serverServerEvaluationCall javascript(java.lang.String javascript)
javascript
- the javascript-syntax source code to eval on the serverServerEvaluationCall javascript(TextWriteHandle javascript)
javascript
- a handle containing the javascript-syntax source code to eval on the serverServerEvaluationCall modulePath(java.lang.String modulePath)
modulePath
- a path to a module previously installed in the serverServerEvaluationCall addVariable(java.lang.String name, java.lang.String value)
name
- the variable name, including a namespace prefix if the prefix is
mapped to a uri in the namespace context
value
- the atomic variable valueServerEvaluationCall addVariable(java.lang.String name, java.lang.Number value)
name
- the variable name, including a namespace prefix if the prefix is
mapped to a uri in the namespace context
value
- the atomic variable valueServerEvaluationCall addVariable(java.lang.String name, java.lang.Boolean value)
name
- the variable name, including a namespace prefix if the prefix is
mapped to a uri in the namespace context
value
- the atomic variable valueServerEvaluationCall addVariable(java.lang.String name, AbstractWriteHandle value)
name
- the variable name, including a namespace prefix if the prefix is
mapped to a uri in the namespace context
value
- the handle containing the variable value, most likely XML or JSONServerEvaluationCall addVariableAs(java.lang.String name, java.lang.Object value)
name
- the variable name, including a namespace prefix if the prefix is
mapped to a uri in the namespace context
value
- the handle containing the variable valueServerEvaluationCall transaction(Transaction transaction)
transaction
- the open transaction under which to run this call in the serverServerEvaluationCall addNamespace(java.lang.String prefix, java.lang.String namespaceURI)
prefix
- the prefix for this mappingnamespaceURI
- the uri for this mappingServerEvaluationCall namespaceContext(EditableNamespaceContext namespaces)
namespaces
- a namespace context specifying the mapping from prefixes to namespaces<T> T evalAs(java.lang.Class<T> responseType) throws ForbiddenUserException, FailedRequestException
T
- the type of object that will be returned by the handle registered for itresponseType
- the type desired for the response. Must be a Class registered
to a handle.ForbiddenUserException
FailedRequestException
<H extends AbstractReadHandle> H eval(H responseHandle) throws ForbiddenUserException, FailedRequestException
H
- the type of AbstractReadHandle to returnresponseHandle
- the type of handle appropriate for the expected single resultForbiddenUserException
FailedRequestException
EvalResultIterator eval() throws ForbiddenUserException, FailedRequestException
ForbiddenUserException
FailedRequestException
Copyright © 2013-2021 MarkLogic Corporation.