ServerEvaluationCall (MarkLogic Java Client API 3.0.2 API)

```
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. Here is a simple "hello world" junit example:
```
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. Here is a simple "hello solar system" example with a variable:
```
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.

Method Summary

Methods
Modifier and Type	Method and Description
`ServerEvaluationCall`	`addNamespace(String prefix, String namespaceURI)` Add a single namespace prefix-to-uri mapping to the namespace context.
`ServerEvaluationCall`	`addVariable(String name, AbstractWriteHandle value)` Set a variable name-value pair to pass to the code executing server-side.
`ServerEvaluationCall`	`addVariable(String name, Boolean value)` Set a variable name-value pair to pass to the code executing server-side.
`ServerEvaluationCall`	`addVariable(String name, Number value)` Set a variable name-value pair to pass to the code executing server-side.
`ServerEvaluationCall`	`addVariable(String name, String value)` Set a variable name-value pair to pass to the code executing server-side.
`ServerEvaluationCall`	`addVariableAs(String name, 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> H`	`eval(H responseHandle)` Provides the single result of the server-side eval or invoke call, wrapped in an io handle.
`<T> T`	`evalAs(Class<T> responseType)` Conveneince method to get the response serialized to a particular type by an io handle.
`ServerEvaluationCall`	`javascript(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(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(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.

- Method Detail
  - xquery
```
ServerEvaluationCall xquery(String xquery)
```
    Initialize this server-side eval with xquery-syntax source code.
    
    Parameters:
    xquery - the xquery-syntax source code to eval on the server
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - xquery
```
ServerEvaluationCall xquery(TextWriteHandle xquery)
```
    Initialize this server-side eval with xquery-syntax source code.
    
    Parameters:
    xquery - a handle containing the xquery-syntax source code to eval on the server
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - javascript
```
ServerEvaluationCall javascript(String javascript)
```
    Initialize this server-side eval with javascript-syntax source code.
    
    Parameters:
    javascript - the javascript-syntax source code to eval on the server
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - javascript
```
ServerEvaluationCall javascript(TextWriteHandle javascript)
```
    Initialize this server-side eval call with javascript-syntax source code.
    
    Parameters:
    javascript - a handle containing the javascript-syntax source code to eval on the server
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - modulePath
```
ServerEvaluationCall modulePath(String modulePath)
```
    Initialize this server-side invoke call with a path to the module to invoke.
    
    Parameters:
    modulePath - a path to a module previously installed in the server
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - addVariable
```
ServerEvaluationCall addVariable(String name,
                               String value)
```
    Set a variable name-value pair to pass to the code executing server-side.
    
    Parameters:
    name - the variable name, including a namespace prefix if the prefix is mapped to a uri in the namespace context
    value - the atomic variable value
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - addVariable
```
ServerEvaluationCall addVariable(String name,
                               Number value)
```
    Set a variable name-value pair to pass to the code executing server-side.
    
    Parameters:
    name - the variable name, including a namespace prefix if the prefix is mapped to a uri in the namespace context
    value - the atomic variable value
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - addVariable
```
ServerEvaluationCall addVariable(String name,
                               Boolean value)
```
    Set a variable name-value pair to pass to the code executing server-side.
    
    Parameters:
    name - the variable name, including a namespace prefix if the prefix is mapped to a uri in the namespace context
    value - the atomic variable value
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - addVariable
```
ServerEvaluationCall addVariable(String name,
                               AbstractWriteHandle value)
```
    Set a variable name-value pair to pass to the code executing server-side.
    
    Parameters:
    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 JSON
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - addVariableAs
```
ServerEvaluationCall addVariableAs(String name,
                                 Object value)
```
    Convenience method to set a variable of a type mapped to an io handle. Like other *As convenience methods throughout the API, the Object value is provided by the handle registered for that Class.
    
    Parameters:
    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
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - transaction
```
ServerEvaluationCall transaction(Transaction transaction)
```
    Initialize this call with a transaction under which server-side execution should occur.
    
    Parameters:
    transaction - the open transaction under which to run this call in the server
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - addNamespace
```
ServerEvaluationCall addNamespace(String prefix,
                                String namespaceURI)
```
    Add a single namespace prefix-to-uri mapping to the namespace context.
    
    Parameters:
    prefix - the prefix for this mapping
    namespaceURI - the uri for this mapping
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - namespaceContext
```
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.
    
    Parameters:
    namespaces - a namespace context specifying the mapping from prefixes to namespaces
    
    Returns:
    a reference to this ServerEvaluationCall instance for use as a fluent-style builder
  - evalAs
```
<T> T evalAs(Class<T> responseType)
         throws ForbiddenUserException,
                FailedRequestException
```
    Conveneince method to get the response serialized to a particular type by an io handle. Like other *As convenience methods throughout the API, the return value is provided by the handle registered for the provided responseType.
    
    Parameters:
    responseType - the type desired for the response. Must be a Class regiestered to a handle.
    
    Returns:
    the result deserialized by the implicit handle mapped to this responseType
    
    Throws:
    
    ForbiddenUserException
    
    FailedRequestException
  - eval
```
<H extends AbstractReadHandle> H eval(H responseHandle)
                                  throws ForbiddenUserException,
                                         FailedRequestException
```
    Provides the single result of the server-side eval or invoke call, wrapped in an io handle.
    
    Parameters:
    responseHandle - the type of handle appropriate for the expected single result
    
    Returns:
    the handle which wraps the response
    
    Throws:
    
    ForbiddenUserException
    
    FailedRequestException
  - eval
```
EvalResultIterator eval()
                        throws ForbiddenUserException,
                               FailedRequestException
```
    Provides all results returned by the server-side eval or invoke call.
    
    Returns:
    an EvalResultIterator which provides access to all the results returned by the server-side eval or invoke call.
    
    Throws:
    
    ForbiddenUserException
    
    FailedRequestException

Interface ServerEvaluationCall

Method Summary

Method Detail

xquery

xquery

javascript

javascript

modulePath

addVariable

addVariable

addVariable

addVariable

addVariableAs

transaction

addNamespace

namespaceContext

evalAs

eval

eval