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 © 2024 MarkLogic Corporation. All Rights Reserved.