Table of Contents Previous Next
Logo
Dynamic Ice : 36.4 Asynchronous Dynamic Invocation and Dispatch
Copyright © 2003-2009 ZeroC, Inc.

36.4 Asynchronous Dynamic Invocation and Dispatch

Ice provides asynchronous support for the dynamic invocation and dispatch models described in Section 36.3. The mappings for the ice_invoke proxy function and the Blobject class adhere to the asynchronous mapping rules in Chapter 33.

36.4.1 C++ Mapping

This section describes the asynchronous C++ mapping for the ice_invoke proxy function and the Blobject class.

ice_invoke_async

The asynchronous mapping for ice_invoke produces a function named ice_invoke_async, as shown below:
bool ice_invoke_async(
    const Ice::AMI_Object_ice_invokePtr& cb,
    const std::string& operation,
    Ice::OperationMode mode,
    const std::vector<Ice::Byte>& inParams
);
Another overloading of ice_invoke_async (not shown) adds a trailing argument of type Ice::Context (see Section 32.12).
The return value and the parameters operation, mode, andinParams have the same semantics as for ice_invoke (see Section 36.3.1). As with any other asynchronous invocation, the first argument to the proxy function is always a callback object. In this case, the callback object must derive from the class Ice::AMI_Object_ice_invoke, shown here:
namespace Ice {
    class AMI_Object_ice_invoke : ... {
    public:
        virtual void ice_response(
            bool result,
            const std::vector<Ice::Byte>& outParams) = 0;

        virtual void ice_exception(const Ice::Exception& ex) = 0;

        // ...
    };  
}  
The ice_response function is invoked for a successful completion or when a user exception occurs. A value of true for the first argument signals success; results from the operation are encoded in the second argument outParams. A value of false for the first argument indicates a user exception was raised, and the encoded form of the exception is provided in outParams.
The ice_exception function is invoked only when the operation raises a local exception such as OperationNotExistException.

BlobjectAsync

BlobjectAsync is the name of the asynchronous counterpart to Blobject:
namespace Ice {
    class BlobjectAsync : virtual public Ice::Object {
    public:
        virtual void ice_invoke_async(
            const AMD_Object_ice_invokePtr& cb,
            const std::vector<Ice::Byte>& inParams,
            const Ice::Current& current) = 0;
    };
}
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:
namespace Ice {
    class AMD_Object_ice_invoke : ... {
    public:
        virtual void ice_response(
            bool result,
            const std::vector<Ice::Byte>& outParams) = 0;
        virtual void ice_exception(const IceUtil::Exception&) = 0;
        virtual void ice_exception(const std::exception&) = 0;
        virtual void ice_exception() = 0;
    };
}
Upon a successful invocation, the servant must invoke ice_response on the callback object, passing true as the first argument and encoding the operation results into outParams. To report a user exception, the servant invokes ice_response with false as the first argument and the encoded form of the exception in outParams.
The various overloadings of ice_exception are discussed in Section 33.4.2. Note however that 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.

Array Mapping

The discussion of the synchronous interfaces on page 1196 presented the array mapping for the ice_invoke proxy functions and the BlobjectArray base class. The array mapping is also supported in the asynchronous interfaces for dynamic invocation and dispatch.
Ice provides two overloaded versions of the proxy function ice_invoke_async that use the array mapping. The version that omits the trailing Ice::Context argument is shown below:
bool ice_invoke_async(
    const Ice::AMI_Array_Object_ice_invokePtr& cb,
    const std::string& operation,
    Ice::OperationMode mode,
    const std::pair<const Ice::Byte*, const Ice::Byte*>& in
);
The AMI callback class also supports the array mapping for the encoded out parameter blob, as you can see in its definition of ice_response:
class AMI_Array_Object_ice_invoke : ... {
public:
    virtual void ice_response(
        bool result,
        const std::pair<const Ice::Byte*, const Ice::Byte*>& out)
        = 0;

    virtual void ice_exception(const Ice::Exception& ex) = 0;

    // ...
};  
To implement an asynchronous Blobject servant that uses the array mapping, derive your implementation class from Ice::BlobjectArrayAsync and override the ice_invoke_async function:
class BlobjectArrayAsync : virtual public Ice::Object {
public:
    virtual void ice_invoke_async(
        const AMD_Array_Object_ice_invokePtr& cb,
        const std::pair<const Ice::Byte*, const Ice::Byte*>& in,
        const Ice::Current& current) = 0;
};
The AMD callback class also supports the array mapping for the encoded out parameter blob, as shown below for ice_response:
class AMD_Array_Object_ice_invoke : ... {
public:
    virtual void ice_response(
        bool result,
        const std::pair<const Ice::Byte*, const Ice::Byte*>& out)
        = 0;
    virtual void ice_exception(const IceUtil::Exception&) = 0;
    virtual void ice_exception(const std::exception&) = 0;
    virtual void ice_exception() = 0;
};
See Section 6.7.4 for more information on the array mapping.

36.4.2 Java Mapping

This section describes the asynchronous Java mapping for the ice_invoke proxy function and the Blobject class.

ice_invoke_async

The asynchronous mapping for ice_invoke produces a function named ice_invoke_async, as shown below:
public abstract boolean ice_invoke_async(
    Ice.AMI_Object_ice_invoke cb,
    String operation,
    Ice.OperationMode mode,
    byte[] inParams
);
Another overloading of ice_invoke_async (not shown) adds a trailing argument of type Ice.Context (see Section 32.12).
The return value and the parameters operation, mode, andinParams have the same semantics as for ice_invoke (see Section 36.3.1). As with any other asynchronous invocation, the first argument to the proxy function is always a callback object. In this case, the callback object must derive from the class Ice.AMI_Object_ice_invoke, shown here:
package Ice;

public abstract class AMI_Object_ice_invoke ... {
    public abstract void ice_response(boolean result,
                                      byte[] outParams);
    public abstract void ice_exception(LocalException ex);
}  
The ice_response function is invoked for a successful completion or when a user exception occurs. A value of true for the first argument signals success; results from the operation are encoded in the second argument outParams. A value of false for the first argument indicates a user exception was raised, and the encoded form of the exception is provided in outParams.
The ice_exception function is invoked only when the operation raises a local exception such as OperationNotExistException.

BlobjectAsync

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 operation results into outParams. To report a user exception, the servant invokes ice_response with false as the first argument and the encoded form of the exception in outParams.
The ice_exception function is discussed in Section 33.4.2. Note however that 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.

36.4.3 C# Mapping

This section describes the asynchronous C# mapping for the ice_invoke proxy function and the Blobject class.

ice_invoke_async

The asynchronous mapping for ice_invoke produces a function named ice_invoke_async, as shown below:
namespace Ice {
    public interface ObjectPrx {
        bool ice_invoke_async(AMI_Object_ice_invoke cb,
                              string operation,
                              OperationMode mode,
                              byte[] inParams);
    }
}
Another overloading of ice_invoke_async (not shown) adds a trailing argument of type Ice.Context (see Section 32.12).
The return value and the parameters operation, mode, andinParams have the same semantics as for ice_invoke (see Section 36.3.1). As with any other asynchronous invocation, the first argument to the proxy function is always a callback object. In this case, the callback object must derive from the class Ice.AMI_Object_ice_invoke, shown here:
namespace Ice {

    public abstract class AMI_Object_ice_invoke : ...
    {
        public abstract void ice_response(
                                bool ok, byte[] outParams);
        public abstract override void ice_exception(
                                Ice.Exception ex);
    }

}
The ice_response function is invoked for a successful completion or when a user exception occurs. A value of true for the first argument signals success; results from the operation are encoded in the second argument outParams. A value of false for the first argument indicates a user exception was raised, and the encoded form of the exception is provided in outParams.
The ice_exception function is invoked only when the operation raises a local exception such as OperationNotExistException.

BlobjectAsync

BlobjectAsync is the name of the asynchronous counterpart to Blobject:
public abstract class BlobjectAsync
    : Ice.ObjectImpl
{
    public abstract void ice_invoke_async(
                        AMD_Object_ice_invoke cb,
                        byte[] inParams,
                        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:
namespace Ice
{
    public interface AMD_Object_ice_invoke
    {
        void ice_response(bool ok, byte[] outParams);
        void ice_exception(System.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 operation results into outParams. To report a user exception, the servant invokes ice_response with false as the first argument and the encoded form of the exception in outParams.
The ice_exception function is discussed in Section 33.4.2. Note however that 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.
Table of Contents Previous Next
Logo