6. CORBA

6.1. What you should know before Reading this section

This section assumes that the reader is familiar with the CORBA specifications described in :cite:`corba` and the IDL-to-Ada mapping defined in :cite:`corba-ada-mapping1.2:2001`.

6.2. Installing CORBA application personality

Ensure PolyORB has been configured and then compiled with the CORBA application personality. See Building an application with PolyORB for more details on how to check installed personalities.

To build the CORBA application personality, Installation.

6.3. IDL-to-Ada compiler

PolyORB provides two IDL-to-Ada compilers:

  • iac is the new, optimized PolyORB IDL-to-Ada compiler.
  • idlac is the legacy PolyORB IDL-to-Ada compiler,

6.3.1. Usage of iac

iac is PolyORB’s new IDL-to-Ada compiler. It supports many command line parameters to control code generation optimizations such as use of static hashing for deterministic request dispatching, and optimized GIOP marshalling for CORBA applications.

NAME
       iac - PolyORB's IDL-to-Ada compiler

SYNOPSIS
       iac [options] file [-cppargs args...]

DESCRIPTION
       iac is an IDL-to-Ada compiler, compliant with version 1.2 of the
       'Ada Language Mapping Specification' produced by the OMG.

OPTIONS
       iac accepts the following options:

  -h       Print this help message, and do nothing else

  file is the name of the .idl file (.idl suffix optional)

  -E       Preprocess only
  -k       Keep temporary files
  -o DIR   Output directory (DIR must exist)
  -p       Produce source on standard output
  -q       Quiet mode

  -dm      Generate debug messages when analyzing scopes

  -df      Dump the frontend tree (the IDL tree)

  -cppargs Pass arguments to the C++ preprocessor
  -I <dir> Shortcut -cppargs -I directory. Use this flag
           for the imported entities
  -nocpp   Do not preprocess input

  -gnatW8  Use UTF-8 character encoding in Ada output.
           (Default is Latin-1.)

  -<lang>  Generate code for one of the following languages:

   types   Generate a list of all types present in the IDL file
           -p       Print the list generated

   ada     (default) Generate Ada source code
           -i       Generate implementation packages
           -c       Generate code for client side only
           -s       Generate code for server side only
           -d       Generate delegation package (defunct)
           -ir      Generate code for interface repository
           -noir    Do not generate code for interface repository (default)
           -hc      Minimize CPU time in perfect hash tables in skels
           -hm      Minimize memory use in perfect hash tables in skels
                    This is the default.
           -rs      Use the SII/SSI to handle requests
           -rd      Use the DII/DSI to handle requests (default)
           -da      Dump the Ada tree
           -db      Generate only the package bodies
           -ds      Generate only the package specs
           -dw      Output the withed entities
           -dt      Output tree warnings
           -di      Generate code for imported entities

   idl     Dump parsed IDL file
           -b n     Base to output integer literals
                    As a default (zero) use base from input
           -e       Expand IDL Tree
           -df      Dump IDL Tree (may be used in conjunction with -e
                    to dump the expanded IDL tree)
           -di      Output IDL code of imported entities  (may be
                    used in conjunction with -e to output the
                    expanded IDL code)

EXIT STATUS
       iac returns one of the following values upon exit:

       0      Successful completion

       1      Usage error

       2      Illegal IDL specification

iac creates several files :

  • myinterface.ads, myinterface.adb : these files contain the mapping for user defined types (client and server side).
  • myinterface-impl.ads, myinterface-impl.adb : these files are to be filled in by the user. They contain the implementation of the server. They are generated only if the -i flag is specified.
  • myinterface.ads, myinterface.adb : these files contain the client stubs for the interface.
  • myinterface-skel.ads, myinterface-skel.adb : these files contain the server-side skeletons for the interface.
  • myinterface-helper.ads, myinterface-helper.adb : these files contain subprograms to marshal data into CORBA Any containers.
  • myinterface-ir_info.ads, myinterface-ir_info.adb : these files contain code for registering IDL definitions in the CORBA Interface Repository. They are generated only if the ‘-ir’ flag is specified.
  • myinterface-cdr.ads, myinterface-cdr.adb : these files contain code for optimized CDR marshalling of GIOP messages. They are generated only if the ‘-rs’ flag is specified.

6.3.2. Usage of idlac

idlac is PolyORB’s IDL-to-Ada compiler.

NAME
       idlac - PolyORB's IDL-to-Ada compiler

SYNOPSIS
       idlac [-Edikpqv] [-[no]ir] [-gnatW8] [-o DIR] idl_file [-cppargs ...]

DESCRIPTION
       idlac is an IDL-to-Ada compiler, compliant with version 1.2 of the
       'Ada Language Mapping Specification' produced by the OMG.

OPTIONS
       idlac accepts the following options:

       -E      Preprocess only.

       -d      Generate delegation package.

       -i      Generate implementation template.

       -s      Generate server side code.

       -c      Generate client side code.

       -k      Keep temporary files.

       -p      Produce source on standard output.

       -q      Be quiet (default).

       -v      Be verbose.

       -ir     Generate code for interface repository.

       -noir   Don't generate code for interface repository (default).

       -gnatW8
               Use UTF8 character encoding

       -o DIR Specify output directory

       -cppargs ARGS
               Pass ARGS to the C++ preprocessor.

       -I dir  Shortcut for -cppargs -I dir.

EXIT STATUS
       idlac returns one of the following values upon exit:

       0      Successful completion

       1      Usage error

       2      Illegal IDL specification

idlac creates several files :

  • myinterface.ads, myinterface.adb : these files contain the mapping for user defined types (client and server side).
  • myinterface-impl.ads, myinterface-impl.adb : these files are to be filled in by the user. They contain the implementation of the server. They are generated only if the -i flag is specified.
  • myinterface.ads, myinterface.adb : these files contain the client stubs for the interface.
  • myinterface-skel.ads, myinterface-skel.adb : these files contain the server-side skeletons for the interface.
  • myinterface-helper.ads, myinterface-helper.adb : these files contain subprograms to marshal data into CORBA Any containers.
  • myinterface-ir_info.ads, myinterface-ir_info.adb : these files contain code for registering IDL definitions in the CORBA Interface Repository. They are generated only if the ‘-ir’ flag is specified.

6.3.3. Difference between idlac and iac

This section lists the main differences between idlac and iac

  • iac is backward compatible with idlac, but lacks the following feature:
    • generation of delegation files.

iac implements additional name clash resolution rules. When the name of an IDL operation clashes with a primitive operation of Ada.Finalization.Controlled (of which CORBA.Object.Ref is a derived type), it is prefixed with “IDL_” in generated sources.

6.4. Resolving names in a CORBA application

PolyORB implements the CORBA COS Naming service.

6.4.1. po_cos_naming

po_cos_naming is a standalone server that supports the CORBA COS Naming specification. When launched, it returns its IOR and corbaloc, which can then be used by other CORBA applications.

If you want po_cos_naming to return the same IOR or corbaloc at each startup, you must set a default listen port for the protocol personalities you use. See Configuring protocol personality preferences for more details.

po_cos_naming can output its IOR directly to a file using the -file <filename> flag. This, in conjonction with the ‘file://’ naming scheme provided by CORBA, provides a convenient way to store initial references to the Naming Service.

Usage: po_cos_naming
 -file <filename> : output COS Naming IOR to 'filename'
 -help : print this help
 [PolyORB command line configuration variables]

6.4.2. Registering the reference to the COS Naming server

You have two ways to register the reference to the root context of the COS Naming server the application will use:

  • Setting up the name_service entry in the [corba] section in your configuration file, name_service is the IOR or corbaloc of the COS Naming server to use. See Using a configuration file for more details.
  • Registering an initial reference using the -ORBInitRef NamingService=<IOR> or -ORBInitRef NamingService=<corbaloc> command-line argument. See the CORBA specifications for more details.
  • Registering an initial reference for NamingService using the CORBA.ORB.Register_Initial_Reference function. See the CORBA specifications for more details.

6.4.3. Using the COS Naming

PolyORB provides a helper package to manipulate the COS Naming in your applications. See PolyORB_specific_APIs for more details.

6.5. The CORBA Interface Repository

PolyORB implements the CORBA Interface Repository.

6.5.1. po_ir

po_ir is a standalone server that supports the CORBA Interface Repository. When launched, it returns its IOR and corbaloc, which can then be used by other CORBA applications.

If you want po_ir to return the same IOR or corbaloc at each startup, you must set a default listen port for the protocol personalities you use. See Configuring protocol personality preferences for more details.

6.5.2. Using the Interface Repository

The IDL-to-Ada compiler generates a helper package that allows you to register all entities defined in your IDL specification in the Interface Repository.

6.6. Building a CORBA application with PolyORB

6.6.1. echo example

We consider building a simple ‘Echo’ CORBA server and client. This application echoes a string. The source code for this example is located in the examples/corba/echo directory in the PolyORB distribution. This applications uses only basic elements of CORBA.

To build this application, you need the following pieces of code:

  • IDL definition of an echo object
  • Implementation code for the echo object
  • Code for client and server nodes

6.6.1.1. IDL definition of an echo object

This interface defines an echo object with a unique method echoString. Per construction, this method returns its argument.

interface Echo {
  string echoString (in string Mesg);
};

6.6.1.2. Implementation code for the echo object

Package Echo.Impl is an implementation of this interface. This implementation follows the IDL-to-Ada mapping.

------------------------------------------------------------------------------
--                                                                          --
--                           POLYORB COMPONENTS                             --
--                                                                          --
--                            E C H O . I M P L                             --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--         Copyright (C) 2002-2012, Free Software Foundation, Inc.          --
--                                                                          --
-- This is free software;  you can redistribute it  and/or modify it  under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  This software is distributed in the hope  that it will be useful, --
-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public --
-- License for  more details.                                               --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
--                  PolyORB is maintained by AdaCore                        --
--                     (email: sales@adacore.com)                           --
--                                                                          --
------------------------------------------------------------------------------

with CORBA;
with PortableServer;

package Echo.Impl is

   --  My own implementation of echo object.
   --  This is simply used to define the operations.

   type Object is new PortableServer.Servant_Base with null record;

   type Object_Acc is access Object;

   function EchoString
     (Self : access Object;
      Mesg : CORBA.String)
     return CORBA.String;

end Echo.Impl;

Note: the body of Echo.Impl must have a dependency on Echo.Skel to ensure the elaboration of skeleton code and the correct setup of PolyORB’s internals.

6.6.1.3. Test code for client and server nodes

Client and server code demonstrate how to make a remote invocation on a CORBA object, and how to set up an object on a server node.

Note: the dependency on PolyORB.Setup.Client or PolyORB.Setup.No_Tasking_Server enforces compile-time configuration, see Sample files.

  • Client code tests a simple remote invocation on an object. It is a no-tasking client. A reference to the object is built from a stringified reference (or IOR), which is passed on command line.
------------------------------------------------------------------------------
--                                                                          --
--                           POLYORB COMPONENTS                             --
--                                                                          --
--                               C L I E N T                                --
--                                                                          --
--                                 B o d y                                  --
--                                                                          --
--         Copyright (C) 2002-2012, Free Software Foundation, Inc.          --
--                                                                          --
-- This is free software;  you can redistribute it  and/or modify it  under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  This software is distributed in the hope  that it will be useful, --
-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public --
-- License for  more details.                                               --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
--                  PolyORB is maintained by AdaCore                        --
--                     (email: sales@adacore.com)                           --
--                                                                          --
------------------------------------------------------------------------------

--  Echo client

with Ada.Command_Line;
with Ada.Text_IO;
with CORBA.ORB;

with Echo;

with PolyORB.Setup.Client;
pragma Warnings (Off, PolyORB.Setup.Client);

with PolyORB.Utils.Report;

procedure Client is
   use Ada.Command_Line;
   use Ada.Text_IO;
   use PolyORB.Utils.Report;
   use type CORBA.String;

   Sent_Msg, Rcvd_Msg : CORBA.String;
   myecho : Echo.Ref;

   Length : Natural := 0;
   Calls  : Natural := 1;
begin
   New_Test ("Echo client");

   CORBA.ORB.Initialize ("ORB");
   if Argument_Count not in 1 .. 3 then
      Put_Line
        ("usage: client <IOR_string_from_server>|-i [strlen [num of calls]]");
      return;
   end if;

   --  Getting the CORBA.Object

   CORBA.ORB.String_To_Object
     (CORBA.To_CORBA_String (Ada.Command_Line.Argument (1)), myecho);

   --  Get optional arguments Length and Calls

   if Argument_Count >= 2 then
      Length := Natural'Value (Ada.Command_Line.Argument (2));
   end if;

   if Argument_Count >= 3 then
      Calls := Natural'Value (Ada.Command_Line.Argument (3));
   end if;

   --  Checking if it worked

   if Echo.Is_Nil (myecho) then
      Put_Line ("main : cannot invoke on a nil reference");
      return;
   end if;

   --  Sending message

   if Length = 0 then
      Sent_Msg := CORBA.To_CORBA_String (Standard.String'("Hello Ada !"));
   else
      Sent_Msg := CORBA.To_CORBA_String
                    (Standard.String'(1 .. Length => 'X'));
   end if;

   for J in 1 .. Calls loop
      Rcvd_Msg := Echo.echoString (myecho, Sent_Msg);
   end loop;

   if Rcvd_Msg /= Sent_Msg then
      raise Program_Error with "incorrect string returned by server";
   end if;

   --  Printing result

   if Length = 0 then
      Put_Line ("I said : " & CORBA.To_Standard_String (Sent_Msg));
      Put_Line
        ("The object answered : " & CORBA.To_Standard_String (Rcvd_Msg));

   else
      Put_Line ("I said : 'X' *" & Length'Img);
      Put_Line ("The object answered the same.");
   end if;

   End_Report;

exception
   when E : CORBA.Transient =>
      Output ("echo test", False);
      declare
         Memb : CORBA.System_Exception_Members;
      begin
         CORBA.Get_Members (E, Memb);
         Put ("received exception transient, minor");
         Put (CORBA.Unsigned_Long'Image (Memb.Minor));
         Put (", completion status: ");
         Put_Line (CORBA.Completion_Status'Image (Memb.Completed));

         End_Report;
      end;
end Client;
  • The server code sets up a no-tasking node. The object is registered to the RootPOA. Then an IOR reference is built to enable interaction with other nodes.
------------------------------------------------------------------------------
--                                                                          --
--                           POLYORB COMPONENTS                             --
--                                                                          --
--                               S E R V E R                                --
--                                                                          --
--                                 B o d y                                  --
--                                                                          --
--         Copyright (C) 2002-2012, Free Software Foundation, Inc.          --
--                                                                          --
-- This is free software;  you can redistribute it  and/or modify it  under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  This software is distributed in the hope  that it will be useful, --
-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public --
-- License for  more details.                                               --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
--                  PolyORB is maintained by AdaCore                        --
--                     (email: sales@adacore.com)                           --
--                                                                          --
------------------------------------------------------------------------------

with Ada.Exceptions;
with Ada.Text_IO; use Ada.Text_IO;

with CORBA.Impl;
with CORBA.Object;
with CORBA.ORB;

with PortableServer.POA.Helper;
with PortableServer.POAManager;

with Echo.Impl;

with PolyORB.CORBA_P.CORBALOC;

--  Setup server node: use no tasking default configuration

with PolyORB.Setup.No_Tasking_Server;
pragma Warnings (Off, PolyORB.Setup.No_Tasking_Server);

procedure Server is
begin

   declare
      Argv : CORBA.ORB.Arg_List := CORBA.ORB.Command_Line_Arguments;

   begin
      CORBA.ORB.Init (CORBA.ORB.To_CORBA_String ("ORB"), Argv);

      declare
         Root_POA : PortableServer.POA.Local_Ref;

         Ref : CORBA.Object.Ref;

         Obj : constant CORBA.Impl.Object_Ptr := new Echo.Impl.Object;

      begin

         --  Retrieve Root POA

         Root_POA := PortableServer.POA.Helper.To_Local_Ref
           (CORBA.ORB.Resolve_Initial_References
            (CORBA.ORB.To_CORBA_String ("RootPOA")));

         PortableServer.POAManager.Activate
           (PortableServer.POA.Get_The_POAManager (Root_POA));

         --  Set up new object

         Ref := PortableServer.POA.Servant_To_Reference
           (Root_POA, PortableServer.Servant (Obj));

         --  Output IOR

         Put_Line
           ("'"
            & CORBA.To_Standard_String (CORBA.Object.Object_To_String (Ref))
            & "'");
         New_Line;

         --  Output corbaloc

         Put_Line
           ("'"
            & CORBA.To_Standard_String
            (PolyORB.CORBA_P.CORBALOC.Object_To_Corbaloc (Ref))
            & "'");

         --  Launch the server. CORBA.ORB.Run is supposed to never return,
         --  print a message if it does.

         CORBA.ORB.Run;

         Put_Line ("ORB main loop terminated!");
      end;
   end;
exception
   when E : others =>
      Put_Line
        ("Echo server raised " & Ada.Exceptions.Exception_Information (E));
      raise;
end Server;

6.6.1.4. Compilation and execution

To compile this demo,

  • Process the IDL file with idlac (or iac)

    $ idlac echo.idl
    
  • Compile the client node

    $ gnatmake client.adb `polyorb-config`
    
  • Compile the server node

    $ gnatmake server.adb `polyorb-config`
    

Note the use of backticks (`). This means that polyorb-config is first executed, and then the command line is replaced with the output of the script, setting up library and include paths and library names.

To run this demo:

  • run server, the server outputs its IOR, a hexadecimal string with the IOR: prefix:

    $ ./server
    Loading configuration from polyorb.conf
    No polyorb.conf configuration file.
    'IOR:01534f410d00000049444c3[..]'
    
  • In another shell, run client, passing cut-and-pasting the complete IOR on the command line:

    $ ./client 'IOR:01534f410d00000049444c3[..]'
    Echoing string: " Hello Ada ! "
    I said : Hello Ada !
    The object answered : Hello Ada !
    

6.6.2. Other examples

PolyORB provides other examples to test other CORBA features. These examples are located in the example/corba directory in the PolyORB distribution.

  • all_functions tests CORBA parameter passing modes (in, out, ..);
  • all_types tests CORBA types;
  • echo is a simple CORBA demo;
  • random is a random number generator;
  • send tests MIOP specific API.

6.7. Configuring a CORBA application

To configure a CORBA application, you need to separately configure PolyORB and the GIOP protocol (or any other protocol personality you wish to use).

6.7.1. Configuring PolyORB

Please refer to Building an application with PolyORB for more information on PolyORB’s configuration.

6.7.2. Configuring GIOP protocol stack for PolyORB

The GIOP protocol is separated from the CORBA application personality. See Configuring the GIOP personality for more information on GIOP’s configuration.

6.7.3. Configuring Security services for PolyORB

PolyORB provides support for some elements of the CORBA Security mechanisms. This sections lists the corresponding configuration parameters.

6.7.3.1. Supported mechasnisms

PolyORB provides support for the following security mechanisms:

  • SSL/TLS protected transport;
  • GSSUP (user/password) authentication mechanism;
  • identity assertion and backward trust evaluation.

6.7.3.2. Compile-time configuration

To enable security support, applications must `with’ one of the predefined setup packages:

  • PolyORB.Setup.Secure_Client - for client side support only;
  • PolyORB.Setup.Secure_Server - for both client and server side support.

6.7.3.3. Run-time configuration

  • Capsule configuration

    This section details the configuration parameters for capsule configuration.

    [security_manager]
    # List of sections for configure client's credentials
    #own_credentials=my_credentials
    #
    # Client requires integrity proteced messages
    #integrity_required=true
    #
    # Client requires confiodentiality protected messages
    #confidentiality_required=true
    #
    # Client requires security association to detect replay (not supported
    for now)
    #detect_replay_required=true
    #
    # Client requires security association to detect message sequence
    errors (not
    # supported for now)
    #detect_misordering_required=true
    #
    # Client requires target authentication
    #establish_trust_in_target_required=true
    #
    # Client requires client authentication (usually not applicable at
    all)
    #establish_trust_in_client_required=true
    #
    # (rare useful)
    #identity_assertion_required=true
    #
    # (rare useful)
    #delegation_by_client_required=true
    
  • Credentials configuration

    This section details configuration parameters for defining a program’s credentials. Depending on the mechanisms used for the transport and authentication layers, the credentials configuration section may define configuration only for one transport mechanism and/or one authentication mechanism.

    #[my_credentials]
    #
    # TLS protected transport mechanism used as transport mechanism
    #transport_credentials_type=tls
    #
    # Connection method. Available methods: tls1, ssl3, ssl2
    #tls.method=tls1
    #
    # Certificate file name
    #tls.certificate_file=my.crt
    #
    # Certificate chain file name
    #tls.certificate_chain_file=
    #
    # Private key file name
    #tls.private_key_file=my.key
    #
    # Name of file, at which CA certificates for verification purposes are
    #located
    #tls.certificate_authority_file=root.crt
    #
    # Name of directory, at which CA certificates for verification
    #purposes are
    # located
    #tls.certificate_authority_path=
    #
    # List of available ciphers
    #tls.ciphers=ALL
    #
    # Verify peer certificate
    #tls.verify_peer=true
    #
    # Fail if client don't provide ceritificate (server only)
    #tls.verify_fail_if_no_peer_certificate=true
    #
    # GSSUP (user/password) mechanism as authentication mechanism
    #authentication_credentials_type=gssup
    #
    # User name
    #gssup.username=username@domain
    #
    # User password
    #gssup.password=password
    #
    # Target name for which user/password pair is applicable
    #gssup.target_name=@domain
    
  • POA configuration

    This section details configuration parameters for defining security characteristics of objects managed by POA. The POA’s name is used as the section name.

    #[MySecurePOA]
    #
    # Unprotected invocations is allowed
    #unprotected_invocation_allowed=true
    #
    # Section name for configuration of used protected transport mechanism
    #(if any)
    #transport_mechanism=tlsiop
    #
    # Section name for configuration of used authentication mechanism (if
    #any)
    #authentication_mechanism=my_gssup
    #
    # Target require client authentication at authentication layer (in
    #addition
    # to authentication at transport layer)
    #authentication_required=true
    #
    # Name of file for backward trust evalutation rules
    #backward_trust_rules_file=file.btr
    #
    # Section name for configuration of authorization tokens authority
    #privilege_authorities=
    
  • TLS protected transport mechanism configuration

    This section details configuration parameters for the TLS protected transport mechanism. The section name for mechanism configuration is defined in the POA configuration.

    [tlsiop]
    # List of access points
    #addresses=127.0.0.1:3456
    
  • GSSUP authentication mechanism

    This section details configuration parameters for the GSSUP authentication mechanism. The section name for mechanism configuration is defined in the POA configuration.

    #[my_gssup]
    #
    # Authentication mechanism
    #mechanism=gssup
    #
    # Target name
    #gssup.target_name=@domain
    #
    # User name/password mapping file
    #gssup.passwd_file=passwd.pwd
    

6.7.4. Command line arguments

The CORBA specifications define a mechanism to pass command line arguments to your application, using the CORBA::ORB:Init method.

For now, PolyORB supports the following list of arguments:

  • InitRef to pass initial reference.

6.8. Implementation Notes

PolyORB strives to support CORBA specifications as closely as possible. However, on rare occasions, the implementation adapts the specifications to actually enable its completion. This section provides information on the various modifications we made.

6.8.1. Tasking

PolyORB provides support for tasking and no-tasking, using configuration parameters. Please refer to Building an application with PolyORB for more information on PolyORB’s configuration.

When selecting a tasking-capable runtime, ORB-related functions are thread safe, following the IDL-to-Ada mapping recommendations.

6.8.2. Implementation of CORBA specifications

In some cases, the CORBA specifications do not describe the semantics of the interface in sufficient detail. We add an Implementation Notes tag to the package specification to indicate the modifications or enhancements we made to the standard.

In some cases, the IDL-to-Ada mapping specifications and the CORBA specifications conflict. We add an Implementation Notes tag to the package specification to indicate this issue. Whenever possible, PolyORB follows the CORBA specifications.

6.8.3. Additions to the CORBA specifications

In some cases, the specifications lack features that may be useful. We add an Implementation Notes tag to the package specification to detail the additions we made to the standard.

In addition to the above, PolyORB follows some of the recommendations derived from the OMG Issues for Ada 2003 Revision Task Force mailing list (see http://www.omg.org/issues/ada-rtf.html for more information).

6.8.4. Interface repository

The documentation of the PolyORB’s CORBA Interface Repository will appear in a future revision of PolyORB.

6.8.5. Policy Domain Managers

You have two ways to register the reference to the CORBA Policy Domain Manager the application will use:

  • Setting up the policy_domain_manager entry in the [corba] section in your configuration file, policy_domain_manager is the IOR or corbaloc of the COS Naming server to use. See Using a configuration file for more details.
  • Registering an initial reference using the -ORB InitRef PolyORBPolicyDomainManager=<IOR> or -ORB InitRef PolyORBPolicyDomainManager=<corbaloc> command-line argument. See the CORBA specifications for more details.
  • Registering an initial reference for PolyORBPolicyDomainManager using the CORBA.ORB.Register_Initial_Reference function. See the CORBA specifications for more details.

6.8.6. Mapping of exceptions

For each exception defined in the CORBA specifications, PolyORB provides the Raise_<excp_name> function, a utility function that raises the exception <excp_name>, along with its exception member. PolyORB also defines the Get_Members function (as defined in the IDL-to-Ada mapping) to provide accessors to retrieve information on the exception.

In addition, for each exception defined in a user-defined IDL specification, the IDL-to-Ada compiler will generate a Raise_<excp_name> function in the Helper package. It is a utility function that raises the exception <excp_name>, along with its exception member.

6.8.7. Additional information to CORBA::Unknown

When a CORBA application raises an Ada exception that is not part of the IDL specifications, nor defined by the CORBA specifications, then this exception is translated into a CORBA::UNKNOWN exception.

To help debugging CORBA applications, PolyORB supports a specific service context to the GIOP protocol personality that conveys exception information. When displaying exception information, server-side specific exception information is delimited by ‘<Invocation Exception Info: ...>’

Here is an example from the all_types example provided by PolyORB.

Exception name: CORBA.UNKNOWN
Message: 4F4D0001M
<Invocation Exception Info: Exception name: CONSTRAINT_ERROR
Message: all_types-impl.adb:315 explicit raise
Call stack traceback locations:
0x84d279c 0x84c1e78 0x84b92c6 0x84b8e9>
Call stack traceback locations:
0x81d0425 0x81d0554 0x81d6d8c 0x81fd02b 0x81fc091 0x82eea12 0x83e4c22 0x807b69a 0xb7a15e3e

Note that call stack tracebacks can be translated into symbolic form using the addr2line utility that comes with GNAT.

6.8.8. Internals packages

PolyORB sometimes declares internal types and routines inside CORBA packages. These entities are gathered into an Internals child package. You should not use these functions: they are not portable, and may be changed in future releases.

6.9. PolyORB’s specific APIs

PolyORB defines packages to help in the development of CORBA programs.

6.9.1. PolyORB.CORBA_P.CORBALOC

------------------------------------------------------------------------------
--                                                                          --
--                           POLYORB COMPONENTS                             --
--                                                                          --
--             P O L Y O R B . C O R B A _ P . C O R B A L O C              --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--         Copyright (C) 2004-2012, Free Software Foundation, Inc.          --
--                                                                          --
-- This is free software;  you can redistribute it  and/or modify it  under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  This software is distributed in the hope  that it will be useful, --
-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public --
-- License for  more details.                                               --
--                                                                          --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception,   --
-- version 3.1, as published by the Free Software Foundation.               --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
--                  PolyORB is maintained by AdaCore                        --
--                     (email: sales@adacore.com)                           --
--                                                                          --
------------------------------------------------------------------------------

--  Helper functions to manage CORBA corbaloc references

with CORBA.Object;

package PolyORB.CORBA_P.CORBALOC is

   function Object_To_Corbaloc
     (Obj : CORBA.Object.Ref'Class)
     return CORBA.String;
   --  Convert reference to corbaloc, return corbaloc of best profile

end PolyORB.CORBA_P.CORBALOC;

6.9.2. PolyORB.CORBA_P.Naming_Tools

------------------------------------------------------------------------------
--                                                                          --
--                           POLYORB COMPONENTS                             --
--                                                                          --
--         P O L Y O R B . C O R B A _ P . N A M I N G _ T O O L S          --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--         Copyright (C) 2001-2012, Free Software Foundation, Inc.          --
--                                                                          --
-- This is free software;  you can redistribute it  and/or modify it  under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  This software is distributed in the hope  that it will be useful, --
-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public --
-- License for  more details.                                               --
--                                                                          --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception,   --
-- version 3.1, as published by the Free Software Foundation.               --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
--                  PolyORB is maintained by AdaCore                        --
--                     (email: sales@adacore.com)                           --
--                                                                          --
------------------------------------------------------------------------------

--  Wrappers for the COS Naming service to facilitate retrievel of object
--  references by IOR or by name.

with Ada.Finalization;

with CORBA.Object;
with CosNaming.NamingContext;

package PolyORB.CORBA_P.Naming_Tools is

   function Locate (Name : CosNaming.Name) return CORBA.Object.Ref;

   function Locate
     (Context : CosNaming.NamingContext.Ref;
      Name    : CosNaming.Name) return CORBA.Object.Ref;
   --  Locate an object given its name, given as an array of name components.

   function Locate
     (IOR_Or_Name : String; Sep : Character := '/') return CORBA.Object.Ref;

   function Locate
     (Context     : CosNaming.NamingContext.Ref;
      IOR_Or_Name : String;
      Sep         : Character := '/') return CORBA.Object.Ref;
   --  Locate an object by IOR or name. If the string does not start with
   --  "IOR:", the name will be parsed before it is looked up, using
   --  Parse_Name below.

   procedure Register
     (Name   : String;
      Ref    : CORBA.Object.Ref;
      Rebind : Boolean := False;
      Sep    : Character := '/');
   --  Register an object by its name by binding or rebinding.
   --  The name will be parsed by Parse_Name below; any necessary contexts
   --  will be created on the name server.
   --  If Rebind is True, then a rebind will be performed if the name
   --  is already bound.

   procedure Unregister (Name : String);
   --  Unregister an object by its name by unbinding it

   type Server_Guard is limited private;
   procedure Register
     (Guard  : in out Server_Guard;
      Name   : String;
      Ref    : CORBA.Object.Ref;
      Rebind : Boolean := False;
      Sep    : Character := '/');
   --  A Server_Guard object is an object which is able to register a server
   --  reference in a naming service (see Register above), and destroy this
   --  name using Unregister when the object disappears (the program terminates
   --  or the Server_Guard object lifetime has expired).

   function Parse_Name
     (Name : String;
      Sep : Character := '/') return CosNaming.Name;
   --  Split a sequence of name component specifications separated with Sep
   --  characters into a name component array. Any leading Sep is ignored.

private

   type Server_Guard is new Ada.Finalization.Limited_Controlled with record
      Name : CORBA.String := CORBA.To_CORBA_String ("");
   end record;

   procedure Finalize (Guard : in out Server_Guard);

end PolyORB.CORBA_P.Naming_Tools;

6.9.3. PolyORB.CORBA_P.Server_Tools

------------------------------------------------------------------------------
--                                                                          --
--                           POLYORB COMPONENTS                             --
--                                                                          --
--         P O L Y O R B . C O R B A _ P . S E R V E R _ T O O L S          --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--         Copyright (C) 2001-2012, Free Software Foundation, Inc.          --
--                                                                          --
-- This is free software;  you can redistribute it  and/or modify it  under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  This software is distributed in the hope  that it will be useful, --
-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public --
-- License for  more details.                                               --
--                                                                          --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception,   --
-- version 3.1, as published by the Free Software Foundation.               --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
--                  PolyORB is maintained by AdaCore                        --
--                     (email: sales@adacore.com)                           --
--                                                                          --
------------------------------------------------------------------------------

--  Helper functions for CORBA servers. Note that using this unit implies
--  using the Portable Object Adapter.

with CORBA.Object;
with PortableServer.POA;

package PolyORB.CORBA_P.Server_Tools is

   pragma Elaborate_Body;

   type Hook_Type is access procedure;
   Initiate_Server_Hook : Hook_Type;
   --  Access to a procedure to be called upon start up.
   --  See Initiate_Server for more details.

   procedure Activate_Server;
   --  Start a new ORB, and initialize the Root POA.
   --
   --  If the Initiate_Server_Hook variable is not null, the designated
   --  procedure will be called after initializing the ORB.

   procedure Initiate_Server (Start_New_Task : Boolean := False);
   --  Calls Activate_Server then starts ORB main loop.
   --  If Start_New_Task is True, a new task will be created and control will
   --  be returned to the caller. Otherwise, the ORB main loop will be executed
   --  in the current context.

   function Get_Root_POA return PortableServer.POA.Local_Ref;
   --  Return the Root_POA attached to the current ORB instance.

   procedure Initiate_Servant
     (S : PortableServer.Servant;
      R : out CORBA.Object.Ref'Class);
   --  Initiate a servant: register a servant to the Root POA.
   --  If the Root POA has not been initialized, initialize it.

   procedure Reference_To_Servant
     (R : CORBA.Object.Ref'Class;
      S : out PortableServer.Servant);
   --  Convert a CORBA.Object.Ref into a PortableServer.Servant.

   procedure Servant_To_Reference
     (S : PortableServer.Servant;
      R : out CORBA.Object.Ref'Class);
   --  Convert a PortableServer.Servant into CORBA.Object.Ref.

   procedure Initiate_Well_Known_Service
     (S    : PortableServer.Servant;
      Name : String;
      R    : out CORBA.Object.Ref'Class);
   --  Make S accessible through a reference appropriate for
   --  generation of a corbaloc URI with a named key of Name.

end PolyORB.CORBA_P.Server_Tools;