--- name: "CORBA::mapping" section: "3pm" platform: "linux" package: "libcorba-orbit-perl" version: "0.4.0-1" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/CORBA::mapping" --- # CORBA::mapping(3pm) MICO::mapping - CORBA mapping for Perl This document describes a mapping of the CORBA system into Perl. It sticks most closely to the mapping in the the *MICO* manpage module, however some reference is also made to the mappings implemented in the *COPE* manpage and ILU/Perl. These systems exhibit a wide diversity in the details of their object adaptors. MICO implements the BOA in a comprehensive fashion, including all activation modes, COPE implements a simpler version of the BOA, and ILU has its own object native adaptor different from the BOA, though it implements some of the BOA specificatoin through compatibility classes. Future Perl CORBA products will presumably implement the new POA standard. For this reason, this document largely avoids specifying object adaptor details, except for a few specific notes. Details about the manner in which the ORB is initialized and interface definitions are loaded are also not specified here. Conformant implementations may either use conventional stubs or access interface definitions in a dynamic manner. (For instance, by loading them from an Interface Repository.) The design goal for this mapping was to allow applications to access the complete CORBA specification to be accessed from Perl in a convenient and concise manner, even when this requires sacrificing some amount of speed or convenience for the ORB implementor. Names in Perl are identical to those in CORBA IDL. For instance, an interface `Foo` defined module `M`, is mapped into the Perl package `Foo::M`. It should be noted however that Perl package names do not constitute nested scopes. That is, within the package `Foo::M1`, the package `Foo::M1::M2` cannot be referred to as `M2`, but must be specified by the fully qualified name `Foo::M1::M2`. Unsigned `short`, `long`, `float`, `double`, and `octet` all map to Perl scalar variables. `char` maps to a string of length 1. `boolean` map as expected for Perl. That is, a CORBA `boolean` maps to "" if false and to 1 if true. A Perl scalar maps to CORBA::TRUE if it is true, and CORBA::FALSE otherwise. The remaining numeric types mapped to blessed objects. `long long` maps to objects in the package `CORBA::LongLong`, `unsigned long long` maps to objects in the package `CORBA::ULongLong`, `long double` maps to objects in the package `CORBA::LongDouble`. `fixed` maps to objects in the package `CORBA::Fixed`. All of these packages provide overloading for the basic numeric operations. For the `CORBA::LongLong`, `CORBA::ULongLong`, and `CORBA::LongDouble`, the mapping is one-to-one. For `CORBA::Fixed`, each object has a scale which is propagated in arithmetic operations, but no fixed number of digits. Arithmetic operations other than division are done at infinite precision; the result of division is truncated at 31 digits. When the CORBA::Fixed object is provided as an argument to a CORBA call with the argument type specified `fixed, the `CORBA::Fixed` object will be rounded to scale `s` and padded or truncated on the left to `d` digits. Providing an value not in one of the above classes to a numeric operation expecting the corresponding type will give the same result as converting the value to a string by Perl's normal rules, then creating a value in the corresponding class from that string.\ A structure maps to a has reference with keys which are the names of the members. That is: ``` struct S { short a; string b; }; ``` maps to the hash reference: ``` { a => 42, b => "some string" } ``` Enumerations map to strings corresponding to the names of the members.\ Sequences of `octet` and `char` map to Perl strings. Other sequences map to array references.\ Arrays map to Perl array references. Multiple dimensional arrays map to nested Perl array references.\ An any maps to a Perl object of type CORBA::Any. The constructor takes two arguments, the type (of type CORBA::TypeCode) and the value. The type and value are accessed via the *type()* and *value()* member functions.\ A union maps into a two element array reference. The first element is the discriminator, the second, value of the arm selected by that discriminator. If the discriminator does not match one of the arms of the union, and their is no default arm, the second element will be an undefined value. Constants defined in IDL map to a Perl subroutine which returns the value of the constant. CORBA objects are mapped into normal Perl objects. The extra information used by MICO is stored in magic attached to the variable, so it does not matter which type of reference the object is. On the client side, stub objects are blessed hash references, which could conceivably be useful information. But it could also change. On the server side, the choice of type is completely up to the implementor. Interface are implemented by deriving from the package corresponding to the interface. ``` package MyAccount; ``` ``` @MyAccount::ISA = qw(Bank::Account); sub new { my $self = bless { current_balance => 0 }; } ``` An object reference for the object will be created when required. That is, when the object is marshalled as the argument or return value from a call, or when an API operation that requires When it is not clear from inheritance what interface the object implements, the method `_set_repoid()` can be used to specify this specifically.This typically comes up when there is implementation inheritance which parallels the interface inheritance For instance, when implementing the following IDL: ``` module Foo { interface A { long foo(); }; interface B : A { long bar(); } } ``` with the following Perl code; ``` package MyA; ``` ``` @MyA::ISA = qw(Foo::A); sub foo { return 1; } ``` ``` package MyB; ``` ``` @MyA::ISA = qw(MyA Foo::B); sub bar { return 2; } ``` ``` sub new { my $self = bless {}; $self->_set_repoid('IDL:Foo/B:1.0'); } ``` The ID must explicitely be given so that it can be determined that `Foo::B` is being implemented, not `Foo::A`. Note that `MyA` must come first in `MyB`'s `@ISA` so that MyA::foo will be found before the default stub for Foo::A. `_set_repoid` must be called before an object reference is created for the servant.\ **Attributes** Attributes are mapped to a pair of methods with names which are the attribute name prepended with `_set_` and `_get_`. The `_set_` method (not present for `readonly` attributes) takes a single parameter of the type of the attribute. The `_get_` method returns a value of the type of the attribute.\ **Operations** Operations are mapped to method calls. `in` parameters are mapped to parameters normally, `inout` parameters get an extra reference, and `out` parameters are returned as part of a list. For instance, the operation: ``` char foo(in long l, inout string b, out float f); ``` would be called as: ``` ($c,$f) = $obj->foo($l, \$s); ``` **A note on the POA** The above mapping tries to blur the distinction between the servant, and the object reference that it incarnates as much as possible. Perl code uses the same object for both operations. (The object reference is attached in some opaque way to to the servant object, and is retrieved as needed). This keeps simple tasks simple, and is completely sufficient when there is a one-to-one correspondence between the servant and object reference. However, the POA allows for more complicated situations where a single servant may incarnate multiple object references. Supplying a servant object where an object reference is needed is then only acceptable when there is a unique object reference for that servant. In other words, if it would be an error to call the *\_this()* method of the servant, it is also an error to use the object as an object reference. Clearly, a Perl interface to an ORB supporting POA modes where multiple object references are incarnated by a single Perl object cannot completely short circuit the ORB when calls are made from Perl, on these object references, as can be done when there is a one-to-one correspondence between object reference and servant. In such circumstances, some sort of forwarding mechanism will be used. Exceptions are implemented using the Error module by Graham Barr. To throw an exception, use the `throw` method in the Exception package: ``` throw MyInterface::MyException field1 => 'red', field2 => 32; ``` To catch an exception, use a `try...catch` statement. ``` try { $foo->runit(); } catch MyInterface::MyException with { $e = shift; print "Caught a $e->{field1} exception"; } ``` Owen Taylor \ [*perl*(1)](/perl/1.md).