=head1 NAME
COPE - CORBA implemented in Perl
=head1 DESCRIPTION
This documents describes the steps you take when writing a CORBA application
in Perl using COPE.
First the basics: the laguage binding used.
=head2 Scalar types
=over 4
=item char
The C<char> type is represented as a 1-character perl string, like 'a'.
=item octet
C<octet> is represented as a perl number, like 200. We could equally well
make C<octet> be exactly the same as C<char>.
=item Integer types
C<long> and C<short> are no problem. C<unsigned long> might internally be
stored as a C<double>, but that should be invisible.
=item Floating-Point types
Perl has those as well.
=back
=head2 Structures
Structures are represented as blessed hashreferences. They inherit from
CORBA::_Struct which implements a generic constructor called C<new>, taking
key,value pairs.
An example:
# struct MyStruct { // IDL
# boolean simple;
# sequence <octet> list;
# }
package MyStruct;
@ISA=qw(CORBA::_Struct);
my $structvar = new MyStruct( simple => 1, list => [0,1,2] );
Every structure also has a TypeCode defined called C<_tc> (in the appropriate
package). In the example case, the typecode would be called $MyStruct::_tc
=head2 Sequences
A sequence is represented as an unblessed array reference, with one
exception:
B<octet sequences> are represented as a perl string, because they tend
to be used for I<blob>-like data.
=head2 Arrays
Are also represented as unblessed array references, also with one exception:
B<char arrays>, which are again perl strings.
What do people think of these exceptions to the rules?
=head2 Enumerations
Are subs with an empty prototype, declared in the appropriate package.
=head2 Strings
Are plain scalars.
=head2 Unions
I haven't looked at them yet (haven't needed them either)
=head2 Objects
Are Perl objects (blessed references)
=head2 TypeCodes
Are Perl objects
=head2 Interfaces
Are Perl classes. This means a package and an @ISA array.
=head2 Operations
Are Perl methods
=head2 Any
Will be a Perl object.
=head2 Exceptions
Are Perl classes inheriting from Experimental::Exception
=head2 Attributes
I now favour the choice the Java people have made: a method taking zero or
one extra arguments, for getting or setting the attribute. This looks the
most readable to me.
=head2 Parameter passing
=over 4
=item in
All types are already scalar in nature, so can be passed as-is. The number
of arguments to a method are always exactly as in the IDL.
=item inout
All non-reference types (numbers and strings) need to be fitted with a \
and can't be literals.
=item out
Same as for inout. I<note:> You need to supply an empty anonymous array or
hash for sequences, structs or arrays.
Objects need a scalar reference.
=back
=head2 Working with TypeCodes
The TypeCodes for basic types are predefined and have names like
$CORBA::_tc_boolean
All non-basic types have their TypeCode stored in $package::_tc
Custom TypeCodes can be built using functions like _create_struct_tc()
=head2 Server side
When implementing a server, we need three logically seperate classes:
=over 4
=item The implementation of your object
This could be an existing class which you decide to give a shiny new
CORBA wrapper
=item A generated Skeleton class
This is what gets called by the ORB. It is responsible for decoding method
arguments and calling the method
=item A mapping class
The Mapping class provides the mapping between I<known> method names the
skeleton class uses and the possibly I<unknown> names in your implementation
class.
=back
=head1 COPYRIGHT
Copyright (c) 1997 Lunatech Research / Bart Schuller <schuller@lunatech.com>
See the file "Artistic" in the distribution for licensing and
(lack of) warranties.
=cut
# $Id: COPE.pod,v 1.2 1997/06/19 14:34:30 schuller Exp $