2005/5/10

--
down ACDK
down Handbook
down Language
down DMI
down Features Profile
See also:
down DMI Client Interface

Kindly hosted at:

DMI Features Profile

Because DMI connects different languages and middle ware technologies, and these languages and middle wares has different language like features a mapping of these features has to be defined.

Content of this chapter:

   Package
   Unit
   Constants and enums
   Unbound methods
     Only supporting functions
     Not supporting functions
   Classes
     Name service for classes and other types
     Derivation over DMI
     Class Elements
       Constructor
       Destructors
       normal methods bound with Object instance
       static methods not bound with Object instance
       Polymorphic methods
       Method Parameters
         Parameters dispatching
         Default parameter values
         Named parameter values
         Return values and void
         Standard parameter passing
         OUT, INOUT parameter passing
         BYVAL parameter passing
       Exception declarations
       oneway methods

Package

A package is file containing executable code and resources. In common this are executables (.exe on windows) and shared library (.dll on windows or .so on linux).

Unit

A unit is a logical group of classes and resources.

Constants and enums

Constants and enums (group of constants) maps a symbolic name to an integer.
Not directly supported by DMI.

Some languages does not have classes, but only methods. For DMI clients (like Tcl and Lisp) this is not unnecessarily a problem, because managing classes can easily mapped into method calls.
For DMI server implementation it is a little bit more complicated.

Not supporting functions

An DMI Client or Server implementation may not support free functions. Standard ACDK DMI also does not support free function. Free function may be mapped to static member functions.

Classes

Name service for classes and other types

All DMI server must support a type of name service for class objects.

Derivation over DMI

A DMI Client can derives from a interface provided by DMI Server.
The DMI Client has to implement an

Class Elements

Constructor

Not all DMI Clients/Server supports Constructor with in the sense of C++:

Constructors stand for allocation and initialization.
more than one Constructors per class can be defined. The constructors has different arguments. To support this in the language, overloading of function with same name but different arguments must be supported.

COM, for example, also does not provides constructors.
A solution for this is to establish factory classes, which acts as constructors.

Destructors

Because memory management differs to the DMI implementations the semantic of destructors. The DMI client should call releaseRef() to the DMI Server object when freeing the proxy object instance. This can be done in finalizer or equal mechanism.
If no automatic mechanism is provided in the DMI Client implementation the user code has to call dispose() (which calls releaseRef()) manually.

normal methods bound with Object instance

static methods not bound with Object instance

COM doesn't support static member methods. Solution on client side is to provide a static Object instance (singleton), which maps to the static member method.

Polymorphic methods

ACDK Object uses overloading in most classes.
Overloaded methods has the same name, but different arguments (count and/or type of arguments).


  void foo(int i);
  void foo(RString str);
  void foo(int i, jlong l);

Some ACDK DMI Server implementation doesn't support overloading (for example CORBA). A mapping of names can be done following ways:

Overloaded DMI Server methods are displayed in a 'named mangled' version for the DMI Client.
The arguments types are encoded in the method names.
The DMI Server methods should be called with flexible call interface, like Anys, VARIANT, ScriptVar. The DMI server itself can map the parameters to the correct method.

ACDK provides for each method and alternative name. By default the first method is only registered by its normal name ("foo"), for all other methods with the same name a number is added to its name ("foo1", "foo2" and so on).
With the Attribute "acdk.tools.mc.MethodAltNameAttribute" the alternative name of a method can be set at compile time (see

Attributes).

Method Parameters

Also known as arguments.

Typed Parameters Parameter values may be typed or not typed.
Tcl for example only provide the type string. All other types has to be encoded into a string.

Parameters dispatching

Some method invocation protocols encode the type information into the parameter passing (like in COM IDispatch) and other does not deliver type information (like standard IIOP in CORBA).

Default parameter values


  void foo(int i, RString n = "hallo", int j = 0);

ACDK DMI Server maps this to multiple methods:


  void foo(int i);
  void foo(int i, RString n);
  void foo(int i, RString n, int j);

DMI Clients has only to support overloading, or they can calling the method with the alternative name.

Named parameter values

Parameter can have names and be addressed by name.
Before the first named argument the argument are passed by position.

DMI Server:


  // ...
  RObject foo(int count, IN(RString) user, IN(RString) pass);
  // ...
<source>
DMI Client VB:
<source lang="vbscript">
' 42 is positional argument
' pass and user are named arguments
set x = obj.foo(42, pass:="bla", user:="ich")

For ACDK Object named argument are supported by default.

Return values and void

Standard parameter passing

Standard parameter passing is to transfer a value from caller to caller.

Basic Types are passed by value.
Object types are passed by reference.

Most DMI clients and server only supports the standard parameter passing.

IN parameter passing For DMI the default parameter passing and parameters which are marked as IN parameters are equally. In the ACDK DMI Server implementation IN parameters are for performance reasons a little bit different implemented:


void foo(IN(RString) str, IN(int) val);
// is 
void foo(const RString&  str, const int& val);

IN parameters are passed by reference (also Object references) but cannot modified by the callee.

OUT, INOUT parameter passing

Some DMI Client and server (ACDK, COM, CORBA) supports also to transfer a value from callee to the caller - in the sense of additionally return values.

Please refer also to:

Method Types

BYVAL parameter passing

Object types normally transfered by reference. This means by the default parameter passing the DMI server gets only a DMI Object proxy handle from the DMI server.
With the BYVAL attributes the Object type will be serialized.

Please refer also to:

Method Types

Exception declarations

ACDK support to declare a list of exceptions which may be thrown by a method. The exceptions must be derived from

acdk::lang::Throwable and always reference to exceptions will be handled.

If a method declares exceptions, the exceptions can be handled with the correct types in remote and script calls. If an thrown exception is not declared in the method signature the exceptions thrown by the server will be thrown (after de-marshaled) as RThrowable's.

oneway methods

In CORBA methods can has the attribute oneway. These methods may return immediately and executed in another thread.

oneway methods must not has return value other that void and no IN or OUT parameters.