Sometimes you need to present the results from a robot execution in real-time, as the robot is executing. In these cases you want the API to return the extracted values immediately instead of waiting for the robot to finish its execution and access the RqlResult.
The API offers the possibility to receive a callback every time
the API receives a value that was returned by the Robot. This is done
Response streaming using
The above example uses the second execute method of the
Request, which expects a
in addition to the name of the cluster to execute the robot on. In this
example we create a
IRobotResponseHandler by extending
AbstractFailFastRobotResponseHandler, which provides
default error handling, so we only need to handle the values returned by
handleReturnedValue method is called whenever the
API receives a returned value from RoboServer. The
AbstractFailFastRobotResponseHandler used in this example,
will throw exceptions in the same way as the non-streaming execute
method. This means that an exception will be thrown in response to any
API exceptions generated by the robot.
IRobotResponseHandler has several methods which
can be grouped into 3 categories.
Methods which are called when the robot's execution state change on RoboServer, such as when it starts and finishes its execution.
Methods which are called when the robot returns data or errors to the API.
||Called when the
||Called when the found RoboServer has accepted the request, and put it into it queue.|
||Called when the RoboServer begins to execute the robot. This usually occurs immediately after the robot has been queued, unless the RoboServer is under heavy load, or used by multiple API clients.|
||Called when the robot is done executing on RoboServer.
IRobotResponseHandler - robot life cycle events
||Called when the robot has executed a Return Value action, and the value has been returned via the socket to the API.|
||Called when the robot raises an API exception. Under
normal circumstances the robot will stop executing after the
first API exception. This behavior can be overridden by using
||Called if the robot executes the Write Log action. This is useful if you wish to provide additional logging info from within a robot.|
IRobotResponseHandler - robot data events
Called if RoboServer generates an error, for instance if the server too busy to process any requests, or if an error occurs inside RoboServer which prevents it from starting the robot.
||Called if an error occurs inside the API. Most commonly if the client looses the connection to RoboServer.|
IRobotResponseHandler - additional error handling
Many of the methods will include a
object, this object can be used to stop for instance in response to a
specific error or value returned.
Some of these methods allow you to throw an RQLException, if you
do this you should be aware of the consequences. The thread that calls
the handler is the thread that calls
means that any exceptions thrown will bubble up the call stack and out
the execute method. If you throw an exception in response to
handleWriteLog it is your responsibility to invoke
Stoppable.stop(), or the robot may continue to execute even
though the call to
Request.Execute() has completed.
Data streaming is most often used in one of the following use cases.
Response and error collecting using
The example above shows how to use a
IRobotResponseHandler that collects returned values and
errors. This type of handler is useful if the robot should continue to
execute even when error are encountered, which can be useful if the
website is unstable and occasionally times out. Notice that only robot
errors (API exceptions) are collected by the handler, if the connection
to RoboServer is lost
Request.Execute() will still throw an
RQLException (and the robot will be stopped by
For more details check the
chm documentation in the