Next: The Dynamic Skeleton Up: No Title Previous: Dynamic Management of

# The Dynamic Invocation Interface

The Dynamic Invocation Interface (or DII) allows applications to invoke operations on CORBA objects about which they have no static information. That is to say the application has not been linked with stub code which performs the remote operation invocation. Thus using the DII applications may invoke operations on any CORBA object, possibly determining the object's interface dynamically by using an Interface Repository.

This chapter presents an overview of the Dynamic Invocation Interface. An toy example use of the DII can be found in the omniORB2 distribution in the `<top>/src/examples/dii` directory. The DII makes extensive use of the type Any, so ensure that you have read chapter 9. For more information refer to the Dynamic Invocation Interface and C++ Mapping sections of the CORBA 2 specification [OMG99a].

# Overview

To invoke an operation on a CORBA object an application needs an object reference, the name of the operation and a list of the parameters. In addition the application must know whether the operation is one-way, what user-defined exceptions it may throw, any user-context strings which must be supplied, a 'context' to take these values from and the type of the returned value. This information is given by the IDL interface declaration, and so is normally made available to the application via the stub code. In the DII this information is encapsulated in the `CORBA::Request` pseudo-object.

To perform an operation invocation the application must obtain an instance of a `Request` object, supply the information listed above and call one of the methods to actually make the invocation. If the invocation causes an exception to be thrown then this may be retrieved and inspected, or the return value on success.

# Pseudo Objects

The DII defines a number of psuedo-object types, all defined in the CORBA namespace. These objects behave in many ways like CORBA objects. They should only be accessed by reference (through `foo_ptr` or `foo_var`), may not be instantiated directly and should be released by calling `CORBA::release()`. A nil reference should only be represented by `foo::_nil()`.

These pseudo objects, although defined in pseudo-IDL in the specification do not follow the normal mapping for CORBA objects. In particular the memory management rules are different - see the CORBA 2 specification [OMG99a] for more details. New instances of these objects may only be created by the ORB. A number of methods are defined in `CORBA::ORB` to do this.

## Request

A `Request` encapsulates a single operation invocation. It may not be re-used - even for another call with the same arguments.

    class Request {
    public:
      virtual Object_ptr        target() const;
      virtual const char*       operation() const;
      virtual NVList_ptr        arguments();
      virtual NamedValue_ptr    result();
      virtual Environment_ptr   env();
      virtual ExceptionList_ptr exceptions();
      virtual ContextList_ptr   contexts();
      virtual Context_ptr       ctxt() const;
      virtual void              ctx(Context_ptr);

      virtual Any& add_in_arg();
      virtual Any& add_in_arg(const char* name);
      virtual Any& add_inout_arg();
      virtual Any& add_inout_arg(const char* name);
      virtual Any& add_out_arg();
      virtual Any& add_out_arg(const char* name);

      virtual void set_return_type(TypeCode_ptr tc);
      virtual Any& return_value();

      virtual Status  invoke();
      virtual Status  send_oneway();
      virtual Status  send_deferred();
      virtual Status  get_response();
      virtual Boolean poll_response();

      static Request_ptr _duplicate(Request_ptr);
      static Request_ptr _nil();
    };

## NamedValue

A pair consisting of a string and a value - encapsulated in an Any. The name is optional. This type is used to encapsulate parameters and returned values.

    class NamedValue {
    public:
      virtual const char* name() const;
      // Retains ownership of return value.

      virtual Any* value() const;
      // Retains ownership of return value.

      virtual Flags flags() const;

      static NamedValue_ptr _duplicate(NamedValue_ptr);
      static NamedValue_ptr _nil();
    };

## NVList

A list of `NamedValue` objects.

    class NVList {
    public:
      virtual ULong count() const;
      virtual NamedValue_ptr add(Flags);
      virtual NamedValue_ptr add_item(const char*, Flags);
      virtual NamedValue_ptr add_value(const char*, const Any&, Flags);
      virtual NamedValue_ptr add_item_consume(char*,Flags);
      virtual NamedValue_ptr add_value_consume(char*, Any*, Flags);
      virtual NamedValue_ptr item(ULong index);
      virtual Status remove (ULong);

      static NVList_ptr _duplicate(NVList_ptr);
      static NVList_ptr _nil();
    };

## Context

Represents a set of context strings. User contexts are not supported by the omniidl2 IDL compiler - and so cannot be used with statically defined operations. However they are supported in the DII.

    class Context {
    public:
      virtual const char* context_name() const;
      virtual CORBA::Context_ptr parent() const;
      virtual CORBA::Status create_child(const char*, Context_out);
      virtual CORBA::Status set_one_value(const char*, const CORBA::Any&);
      virtual CORBA::Status set_values(CORBA::NVList_ptr);
      virtual CORBA::Status delete_values(const char*);
      virtual CORBA::Status get_values(const char* start_scope,
                                       CORBA::Flags op_flags,
                                       const char* pattern,
                                       CORBA::NVList_out values);
      // Throws BAD_CONTEXT if <start_scope> is not found.
      // Returns a nil NVList in <values> if no matches are found.

      static Context_ptr _duplicate(Context_ptr);
      static Context_ptr _nil();
    };

## ContextList

A `ContextList` is a list of strings, and is used to specify which strings from the 'context' should be sent with an operation.

    class ContextList {
    public:
      virtual ULong count() const;
      virtual void add(const char* ctxt);
      virtual void add_consume(char* ctxt);
      // consumes ctxt

      virtual const char* item(ULong index);
      // retains ownership of return value

      virtual Status remove(ULong index);

      static ContextList_ptr _duplicate(ContextList_ptr);
      static ContextList_ptr _nil();
    };

## ExceptionList

`ExceptionList`s contain a list of TypeCodes - and are used to specify which user-defined exceptions an operation may throw.

    class ExceptionList {
    public:
      virtual ULong count() const;
      virtual void add(TypeCode_ptr tc);
      virtual void add_consume(TypeCode_ptr tc);
      // Consumes <tc>.

      virtual TypeCode_ptr item(ULong index);
      // Retains ownership of return value.

      virtual Status remove(ULong index);

      static ExceptionList_ptr _duplicate(ExceptionList_ptr);
      static ExceptionList_ptr _nil();
    };

## UnknownUserException

When a user-defined exception is thrown by an operation it is unmarshalled into a value of type Any. This is encapsulated in an `UnknownUserException`. This type follows all the usual rules for user-defined exceptions - it is not a pseudo object, and its resources may be released by using `delete`.

    class UnknownUserException : public UserException {
    public:
      UnknownUserException(Any* ex);
      // Consumes <ex> which MUST be a UserException.

      virtual ~UnknownUserException();

      Any& exception();

      virtual void _raise();
      static const UnknownUserException* _downcast(const Exception*);
      static UnknownUserException* _downcast(Exception*);
      static UnknownUserException* _narrow(Exception*);
      // _narrow is a deprecated function from CORBA 2.2,
      // use _downcast instead.
    };

## Environment

An `Environment` is used to hold an instance of a system exception or an `UnknownUserException`.

    class Environment {
      virtual void exception(Exception*);
      virtual Exception* exception() const;
      virtual void clear();

      static Environment_ptr _duplicate(Environment_ptr);
      static Environment_ptr _nil();
    };

# Creating Requests

`CORBA::Object` defines three methods which may be used to create a `Request` object which may be used to perform a single operation invocation on that object:

    class Object {
      ...
      Status _create_request(Context_ptr ctx,
                             const char* operation,
                             NVList_ptr arg_list,
                             NamedValue_ptr result,
                             Request_out request,
                             Flags req_flags);

      Status _create_request(Context_ptr ctx,
                             const char* operation,
                             NVList_ptr arg_list,
                             NamedValue_ptr result,
                             ExceptionList_ptr exceptions,
                             ContextList_ptr ctxlist,
                             Request_out request,
                             Flags req_flags);

      Request_ptr _request(const char* operation);
      ...
    };

`operation` is the name of the operation - which is the same as the name given in IDL. To access attributes the name should be prefixed by `_get_` or `_set_`.

In the first two cases above the list of parameters may be supplied. If the parameters are not supplied in these cases, or `_request()` is used then the parameters (if any) may be specified using the `add_*_arg()` methods on the `Request`. You must use one method or the other - not a mixture of the two. For in/inout arguments the value must be initialised, for out arguments only the type need be given. Similarly the type of the result may be specified by passing a `NamedValue` which contains an Any which has been initialised to contain a value of that type, or it may be specified using the `set_return_type()` method of `Request`.

When using `_create_request()`, the management of any pseudo-object references passed in remains the responsibility of the application. That is, the values are not consumed - and must be released using `CORBA::release()`. The CORBA specification is unclear about when these values may be released, so to be sure of portability do not release them until after the request has been released. Values which are not needed need not be supplied - so if no parameters are specified then it defaults to an empty parameter list. If no result type is specified then it defaults to void. A `Context` need only be given if a non-empty `ContextList` is specified. The `req_flags` argument is not used in the C++ mapping.

## Examples

An operation might be specified in IDL as:

    short anOpn(in string a);

An operation invocation may be created as follows:

    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv, "omniORB2");
    ...
    CORBA::NVList_var args;
    orb->create_list(1, args);
    *(args->add(CORBA::ARG_IN)->value()) <<= (const char*) "Hello World!";

    CORBA::NamedValue_var result;
    orb->create_named_value(result);
    result->value()->replace(CORBA::_tc_short, 0);

    CORBA::Request_var req = obj->_create_request(CORBA::Context::_nil(),
                                            "anOpn", args, result, 0);

or alternatively and much more concisely:

    CORBA::Request_var req = obj->_request("anOpn");
    req->add_in_arg() <<= (const char*) "Hello World!";
    req->set_return_type(CORBA::_tc_short);

# Invoking Operations

Once the `Request` object has been properly constructed the operation may be invoked by calling one of the following methods on the request object:

#### invoke()

blocks until the request has completed. The application should then test to see if an exception was raised. Since the CORBA spec is not clear about whether or not system exceptions should be thrown from this method, a runtime configuration variable is supplied so that you can specify the behavior:

    namespace omniORB {
      ...
      CORBA::Boolean diiThrowsSysExceptions;
      ...
    };

If this is FALSE, and the application should call the `env()` method of the request to retrieve an exception (it returns 0 (nil) if no exception was generated). If it is TRUE then system exceptions will be thrown out of `invoke()`. User-defined exceptions are always passed via `env()`, which will return a pointer to a `CORBA::UnknownUserException`. The application can determine which type of exception was returned by `env()` by calling the `_narrow()` method defined for each exception type.

WARNING!! In pre-omniORB 2.8.0 releases, the default value of `diiThrowsSysExceptions` is FALSE. From omniORB 2.8.0 onwards, the default value is TRUE.

After determining that no exception was thrown the application may retrieve any returned values by calling `return_value()` and `arguments()`.

#### send_oneway()

has the same semantics as a oneway IDL operation. It is important to note that oneway operations have at-most-once semantics, and it is not guaranteed that they will not block. Any operation may be invoked 'oneway' using the DII, even if it was not declared as 'oneway' in IDL. A system exception may be generated, in which case it will either be thrown or may be retrieved using `env()` depending on `diiThrowsSysExceptions` as above.

#### send_deferred()

initiates the invocation, and then returns without waiting for the result. At some point in the future the application must retrieve the result of the operation - but other than testing for completion of the operation the application must not call any of the request's methods in the meantime.

- `get_response()` blocks until the reply is received.
- `poll_response()` returns TRUE if the reply has been received, and FALSE if not. It does not block.

Once `poll_response()` has returned TRUE, or `get_response()` has been called and returned, the application may test for an exception and retrieve returned values as above. If `diiThrowsSysExceptions` is true, then a system exception may be thrown from `get_response()`. From omniORB 2.8.0 onwards, `poll_response()` will raise a system exception if one has occured during the invocation. Previously, `poll_response()` will not raise an exception, so if polling, the application must also call another method to give the request an opportunity to raise the exception. This can be one of the methods to retrieve values from the request, or `get_response()`.

# Multiple Requests

The following methods are provided by the ORB to enable multiple requests to be invoked asynchronously.

    namespace CORBA {
      ...
      class ORB {
      public:
        ...
        Status send_multiple_requests_oneway(const RequestSeq&);
        Status send_multiple_requests_deferred(const RequestSeq&);
        Boolean poll_next_response();
        Status get_next_response(Request_out);
        ...
      };
      ...
    };

#### send_multiple_requests_oneway()

is used to invoke a number of oneway requests. An attempt will be made to invoke each of the requests, even if one or more of the early requests fails. The application may check for failure of any of the requests by testing the request's `env()` method. System exceptions are never raised by this method.

#### send_multiple_requests_deferred()

will initiate an invocation of each of the given requests, and return without waiting for the reply. At some point in the future the application must retrieve the reply by calling `get_next_response()`, which returns a completed request. If no requests have yet completed it will block. This method never throws exceptions - the request's `env()` method must be used to determine if an exception was generated. If not then any returned values may then be queried.

`poll_next_response()` returns TRUE if there are any completed requests, and FALSE otherwise, without blocking. If this returns true then the next call to `get_next_response()` will not block. However, if another thread may also be calling `get_next_response()` then it could retrieve the completed message first - in which case this thread might block.

There are no guarantee as to the order in which replies will be received. If multiple threads are using this interface then it is not even guaranteed that a thread will receive replies to the requests it sent. Any thread may receive replies to requests sent by any other thread. It is legal to call `get_next_response()` even if no requests have yet been invoked - in which case the calling thread blocks until another thread invokes a request and the reply is received.

Next: The Dynamic Skeleton Up: No Title Previous: Dynamic Management of