CORBA::omniORB::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 CORBA::MICO, L:<CORBA:omniORB>, and CORBA::ORBit modules; however, some reference is also made to the mappings implemented in COPE and ILU/Perl.
These systems exhibit a wide diversity in the details of their object adaptors. CORBA::MICO and CORBA::omniORB implement most of the POA specification fashion, including all activation modes. COPE implements a 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.
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 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 in module M, is mapped into the Perl package M::Foo.
Foo
M
M::Foo
It should be noted however that Perl package names do not constitute nested scopes. That is, within the package M::Foo, the package M:Foo::Bar cannot be referred to as Bar, but must be specified by the fully qualified name M::Foo::Bar.
M:Foo::Bar
Bar
M::Foo::Bar
Also, there is no inheritance of scope. If a constant M::Foo::const1 is defined in M::Foo and M::Bar inherits from M::Foo, this constant cannot be referred to as M::Bar::const1.
M::Foo::const1
M::Bar
M::Bar::const1
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.
short
long
float
double
octet
char
boolean
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.
long long
CORBA::LongLong
unsigned long long
CORBA::ULongLong
long double
CORBA::LongDouble
fixed
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<d,s>, the CORBA::Fixed object will be rounded to scale s and padded or truncated on the left to d digits.
fixed<d,s
s
d
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 hash 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 there 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 object references are opaque perl objects.
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
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.
_set_
_get_
readonly
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.
in
inout
out
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);
Exceptions are implemented using the Error module by Graham Barr. To throw an exception, use the throw method in the Exception package:
throw
throw MyInterface::MyException field1 => 'red', field2 => 32;
To catch an exception, use a try...catch statement.
try...catch
try { $foo->runit(); } catch MyInterface::MyException with { $e = shift; print "Caught a $e->{field1} exception"; }
The POA supports modes of operation where a single servant may incarnate multiple object references. For this reason, it is not, in general, permissible to supply a servant where an object reference is required. However, in situations where it is valid to call the _this() method of the servant, an ORB may do this transparently when a servant is used in place of an object reference.
Interface are implemented by deriving from the package corresponding to the interface prepended with "POA_".
package MyAccount; @MyAccount::ISA = qw(POA_Bank::Account); sub new { my $self = bless { current_balance => 0 }; }
If the implementation of a interface in addition from the implementation of a base interface, then the module for the interface being implemented must appear in the @ISA array before the base interface implementation.
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(Foo::B MyA); sub bar { return 2; } sub new { my $self = bless {}; }
Foo:B must come first in MyB's @ISA.
Foo:B
MyB
@ISA
Operations and attributes are implemented exactly as expected from the client-side mapping. That is, the operation is called with the same parameters as a client would use to invoke the operation.
In general, the POA routines map from their description in the .IDL file as specified above. One major exception to this rule is the policy objects and the create_POA routine. There are no policy objects, instead, the create_POA routine is variadic, with the additional arguments being key-value pairs specifying Policy values.
For instance,
$root_poa->create_POA ("MyPOA", undef, id_assignment => 'MULTIPLE_ID', lifetime => 'PERSISTENT');
The opaque Cookie type maps to an arbitary Perl value.
Owen Taylor <otaylor@redhat.com>
perl(1).
2 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
=back without =over
To install CORBA::omniORB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CORBA::omniORB
CPAN shell
perl -MCPAN -e shell install CORBA::omniORB
For more information on module installation, please visit the detailed CPAN module installation guide.