ResultHandle (MINER Clientlib)

Object
- at.srfg.miner.clientlib.ResultHandle

```
public class ResultHandle
extends Object
```
A ResultHandle is created via Action.produce(java.lang.String) and is subsequently needed to retrieve results produced by a tool.
A MINER Tool defines the set of results that it can possibly produce. A client must specify explicitly which of these results shall be produced in an action. This is done via the Action.produce(java.lang.String) method. The return value of this method is a ResultHandle which enables a client to retrieve result instances. Normally, this is done by invoking the appropriate methods of the Execution class, e.g. Execution.nextResults(ResultHandle).
If an action runs on multiple ToolProxies then each ToolProxy is asked to produce the results that are requested in this action. This does not necessarily mean that each ToolProxy of the action will indeed produce all result instances. As an example, there can be a MINER Tool which always requires to be run on 2 ToolProxies: a sender side and a receiver side. Let's assume that a specific result, say 'loss', is computed on the receiver side and thus only the receiver side ToolProxy will generate loss instances.
If a resultHandle is tied to an action with multiple ToolProxies, a result query with this handle queries the database for results from each ToolProxy of this action, i.e. once for ToolProxy 'A', once for ToolProxy 'B' etc. This is the default behavior of a resultHandle which can't know that e.g. 'loss' results, as in the previous example, will always only be available at ToolProxy 'B'.
A user can, however, restrict the set of ToolProxies whose results are queried with this handle by invoking setQueryProxies(java.util.Collection<at.srfg.miner.clientlib.Proxy>).
Example
In this example, the 'stats' results are queried from both proxies while the 'loss' result is only queried from proxy2. The user knows (from the documentation of com.SomeTool) that com.SomeTool does never produce 'loss' results on the sender-side proxy (which we assume is proxy1 in this example) and thus querying for these non-existing results is merely a performance penalty.
```
 action.setTool("com.SomeTool");
 action.addProxy("proxy1");
 action.addProxy("proxy2");
 ResultHandle hStats = action.produce("stats");
 ResultHandle hLoss = action.produce("loss");
 hLoss.setQueryProxies("proxy2");
 
 exec.nextResults(hLoss);
 
```
As soon as a ResultHandle is used in a query for the first time it becomes immutable and trying to reconfigure it via one of the setter methods will throw an IllegalStateException.

Method Summary

Methods
Modifier and Type	Method and Description
`ResultHandle`	`configure(String name, double value)` Configures the tool result.
`Double`	`getConfig(String name)` Get the value for the result configuration parameter `name`.
`String`	`getDatatype()` Gets the datatype of this result handle.
`Integer`	`getID()` Retrieves the identifier of this result handle.
`boolean`	`getIsStored()` Queries if the results will be stored at the server.
`String`	`getName()` Gets the name of the tool result.
`int`	`getReportInterval()` Gets the number of result instances that must accumulate before the ToolProxy sends them to the server.
`String`	`getSavePattern()` Gets the savePattern.
`String`	`getSelector()` Gets the result selector.
`boolean`	`isBinary()` Checks if the handle references a result of type binary.
`ResultHandle`	`setIsStored(boolean isStored)` Defines if the results have to be stored at the server (true, default behavior) or if result instances are only used to evaluate conditions and are discarded afterwards.
`ResultHandle`	`setQueryProxies(Collection<Proxy> proxies)` Defines the proxies whose results will be queried with this resultHandle.
`ResultHandle`	`setQueryProxies(Proxy... proxies)` Defines the proxies whose results will be queried with this resultHandle.
`ResultHandle`	`setQueryProxies(String... proxies)` Defines the proxies whose results will be queried with this resultHandle.
`ResultHandle`	`setReportInterval(int interval)` Sets the number of result instances that must accumulate before the ToolProxy sends them to the server.
`ResultHandle`	`setSavePattern(String savePattern)` Defines a savePattern that is employed when result instances of this handle are saved.
`ResultHandle`	`setSelector(String selector)` Sets the result selector.
`String`	`toString()`

Methods inherited from class Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - getName
```
public String getName()
```
    Gets the name of the tool result.
    
    Returns:
    the result name
  - setQueryProxies
```
public ResultHandle setQueryProxies(Collection<Proxy> proxies)
```
    Defines the proxies whose results will be queried with this resultHandle. Note that proxies must be a subset of the proxies on which the action of this resultHandle is running. This method is only effective if called before the first result retrieval - it has no effect after that.
    
    Parameters:
    proxies - the proxies whose results will be queried with this resultHandle
    
    Returns:
    a self reference
    
    Throws:
    
    IllegalArgumentException - is proxies is null or empty.
  - setQueryProxies
```
public ResultHandle setQueryProxies(String... proxies)
```
    Defines the proxies whose results will be queried with this resultHandle. Note that proxies must be a subset of the proxies on which the action of this resultHandle is running. This method is only effective if called before the first result retrieval - it has no effect after that.
    
    Parameters:
    proxies - the proxies whose results will be queried with this resultHandle
    
    Returns:
    a self reference
    
    Throws:
    
    IllegalArgumentException - is proxies is null or empty.
  - setQueryProxies
```
public ResultHandle setQueryProxies(Proxy... proxies)
```
    Defines the proxies whose results will be queried with this resultHandle. Note that proxies must be a subset of the proxies on which the action of this resultHandle is running. This method is only effective if called before the first result retrieval - it has no effect after that.
    
    Parameters:
    proxies - the proxies whose results will be queried with this resultHandle.
    
    Returns:
    a self reference
    
    Throws:
    
    IllegalArgumentException - is proxies is null or empty.
  - setSelector
```
public ResultHandle setSelector(String selector)
```
    Sets the result selector.
    
    Parameters:
    selector - the selector
    
    Returns:
    a self reference
  - getSelector
```
public String getSelector()
```
    Gets the result selector.
    
    Returns:
    the result selector
  - setIsStored
```
public ResultHandle setIsStored(boolean isStored)
```
    Defines if the results have to be stored at the server (true, default behavior) or if result instances are only used to evaluate conditions and are discarded afterwards.
    
    Parameters:
    isStored - true if results have to be stored, false otherwise.
    
    Returns:
    a self reference
  - getIsStored
```
public boolean getIsStored()
```
    Queries if the results will be stored at the server.
    
    Returns:
    true if the results will be stored at the server.
  - setReportInterval
```
public ResultHandle setReportInterval(int interval)
```
    Sets the number of result instances that must accumulate before the ToolProxy sends them to the server.
    
    Parameters:
    interval - the number of results.
    
    Returns:
    a self reference
  - getReportInterval
```
public int getReportInterval()
```
    Gets the number of result instances that must accumulate before the ToolProxy sends them to the server.
    
    Returns:
    the number of results
  - setSavePattern
```
public ResultHandle setSavePattern(String savePattern)
```
    Defines a savePattern that is employed when result instances of this handle are saved. The pattern may contain a relative or absolute path prefix. If the pattern contains no suffix, ".bin" is appended for binary results and ".txt" is appended otherwise.
    Note that generally results are not automatically retrieved (let alone saved) from the MINER Core. When results are retrieved, e.g. via Execution.nextResults(at.srfg.miner.clientlib.ResultHandle), they are also not saved unless they are of type binary.
    For binary results each result instance is saved to a separate file, therefore savePattern is not the final savePattern but rather a skeleton name which is extended by result properties to create a unique file name.
    For non-binary results where all result instances are stored in a single file, the savePattern equals the final savePattern. The usage of this method for non-binary results is beneficial when invoking Results.getAndSave(at.srfg.miner.clientlib.Execution, at.srfg.miner.clientlib.ResultHandle...) later on.
    
    Parameters:
    savePattern - the savePattern prefix
    
    Returns:
    a self reference
  - getSavePattern
```
public String getSavePattern()
```
    Gets the savePattern. For binary results, this name is automatically used as a savePattern prefix. For all other results it is used as the complete savePattern if they are saved via Results.getAndSave(at.srfg.miner.clientlib.Execution, at.srfg.miner.clientlib.ResultHandle...).
    The savePattern may contain a relative or absolute path.
    
    Returns:
    the savePattern
  - configure
```
public ResultHandle configure(String name,
                     double value)
```
    Configures the tool result.
    
    Parameters:
    name - the configuration name
    value - the configuration value
    
    Returns:
    a self reference
  - getConfig
```
public Double getConfig(String name)
```
    Get the value for the result configuration parameter name.
    
    Parameters:
    name - the name of the result configuration parameter
    
    Returns:
    the value or null if no configuration for name exists.
  - getID
```
public Integer getID()
```
    Retrieves the identifier of this result handle. The identifier is null if the containing scenario was not yet submitted to the MINER core.
    
    Returns:
    the identifier
  - getDatatype
```
public String getDatatype()
```
    Gets the datatype of this result handle. The datatype is null if the scenario containing this resultHandle was not yet submitted to the MINER core.
    
    Returns:
    the datatype as a String identifier
  - isBinary
```
public boolean isBinary()
```
    Checks if the handle references a result of type binary.
    
    Returns:
    true if the referenced result is a binary type.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class ResultHandle

Method Summary

Methods inherited from class Object

Method Detail

getName

setQueryProxies

setQueryProxies

setQueryProxies

setSelector

getSelector

setIsStored

getIsStored

setReportInterval

getReportInterval

setSavePattern

getSavePattern

configure

getConfig

getID

getDatatype

isBinary

toString