This page describes the asynchronous Java mapping for the ice_invoke proxy function and the Blobject class.
On this page:
Calling ice_invoke Asynchronously in Java
The asynchronous mapping for ice_invoke resembles that of the static AMI mapping. Multiple overloadings are provided to support callback styles and request contexts. The return value and the parameters operation, mode, and inParams have the same semantics as for the synchronous version of ice_invoke.
Basic Asynchronous Mapping for ice_invoke in Java
The basic mapping is shown below:
package com.zeroc.Ice;
public interface Object
{
public class Ice_invokeResult
{
public Ice_invokeResult()
{
}
public Ice_invokeResult(boolean returnValue, byte[] outParams)
{
this.returnValue = returnValue;
this.outParams = outParams;
}
public boolean returnValue;
public byte[] outParams;
}
...
}
public interface ObjectPrx
{
java.util.concurrent.CompletableFuture<com.zeroc.Ice.Object.Ice_invokeResult> ice_invokeAsync(
String operation,
OperationMode mode,
byte[] inParams);
java.util.concurrent.CompletableFuture<com.zeroc.Ice.Object.Ice_invokeResult> ice_invokeAsync(
String operation,
OperationMode mode,
byte[] inParams,
java.util.Map<String, String> context);
...
}
As for statically-typed asynchronous invocations, the return value is a CompletableFuture. Its result is an instance of Object.Ice_invokeResult. Run-time exceptions cause the future to fail exceptionally, however user exceptions cause the future to succeed: the returnValue member of the Ice_invokeResult object will be set to false, and the outParams member contains the encapsulated user exception data.
Ice.AsyncResult begin_ice_invoke(
String operation,
Ice.OperationMode mode,
byte[] inParams);
Ice.AsyncResult begin_ice_invoke(
String operation,
Ice.OperationMode mode,
byte[] inParams,
java.util.Map<String, String> __context);
boolean end_ice_invoke(Ice.ByteSeqHolder outParams, Ice.AsyncResult __result);
User exceptions are handled differently than for static asynchronous invocations. Calling end_ice_invoke can raise run-time exceptions but never raises user exceptions. Instead, the boolean return value of end_ice_invoke indicates whether the operation completed successfully (true) or raised a user exception (false). If the return value is true, the byte sequence contains an encapsulation of the results; otherwise, the byte sequence contains an encapsulation of the user exception.
Generic Asynchronous Callback Mapping for ice_invoke in Java Compat
The generic callback API is also available:
Ice.AsyncResult begin_ice_invoke(
String operation,
Ice.OperationMode mode,
byte[] inParams,
Ice.Callback cb);
Ice.AsyncResult begin_ice_invoke(
String operation,
Ice.OperationMode mode,
byte[] inParams,
java.util.Map<String, String> context,
Ice.Callback cb);
Refer to the static AMI mapping for an example of subclassing Ice.Callback.
Type-Safe Asynchronous Callback Mapping for ice_invoke in Java Compat
The type-safe callback API looks as follows:
Ice.AsyncResult begin_ice_invoke(
String operation,
Ice.OperationMode mode,
byte[] inParams,
Ice.Callback_Object_ice_invoke cb);
Ice.AsyncResult begin_ice_invoke(
String operation,
Ice.OperationMode mode,
byte[] inParams,
java.util.Map<String, String> context,
Ice.Callback_Object_ice_invoke cb);
Callers must supply a subclass of Ice.Callback_Object_ice_invoke:
package Ice;
public abstract class Callback_Object_ice_invoke extends ...
{
public abstract void response(boolean ret, byte[] outParams);
public abstract void exception(LocalException ex);
}
The boolean argument to response indicates whether the operation completed successfully (true) or raised a user exception (false). If the return value is true, the byte sequence contains an encapsulation of the results; otherwise, the byte sequence contains an encapsulation of the user exception.
Subclassing BlobjectAsync in Java
BlobjectAsync is the name of the asynchronous counterpart to Blobject:
package com.zeroc.Ice;
public interface BlobjectAsync extends com.zeroc.Ice.Object
{
java.util.concurrent.CompletionStage<Object.Ice_invokeResult> ice_invokeAsync(byte[] inEncaps, Current current)
throws UserException;
}
To implement asynchronous dynamic dispatch, a server must implement BlobjectAsync and define ice_invokeAsync.
The return value for successful completion, or for a user exception, is a CompletionStage whose result is an instance of Object.Ice_invokeResult. The servant may optionally raise a user exception directly and the Ice run time will marshal it for you.
package Ice;
public abstract class BlobjectAsync extends Ice.ObjectImpl
{
public abstract void ice_invoke_async(
Ice.AMD_Object_ice_invoke cb,
byte[] inParams,
Ice.Current current);
// ...
}
To implement asynchronous dynamic dispatch, a server must subclass BlobjectAsync and override ice_invoke_async.
As with any other asynchronous operation, the first argument to the servant's member function is always a callback object. In this case, the callback object is of type Ice.AMD_Object_ice_invoke, shown here:
package Ice;
public interface AMD_Object_ice_invoke
{
void ice_response(boolean result, byte[] outParams);
void ice_exception(java.lang.Exception ex);
}
Upon a successful invocation, the servant must invoke ice_response on the callback object, passing true as the first argument and encoding the encapsulated operation results into outParams. To report a user exception, the servant invokes ice_response with false as the first argument and the encapsulated form of the exception in outParams. Alternatively, the servant can pass a user exception instance to ice_exception.