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 the use of callbacks 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:
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 system 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
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
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 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
.
In the dynamic dispatch model, the ice_exception
function must not be used to report user exceptions; doing so results in the caller receiving UnknownUserException
.
See Also
- Asynchronous Method Invocation (AMI) in Java
- Request Contexts
- Dynamic Invocation and Dispatch Overview