     [file version.texi not included]

PolyORB User's Guide
********************

PolyORB User's Guide

Jérôme Hugues

Copyright © 2003, 2004, 2005, 2006, Free Software Foundation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU Free Documentation License'', with the Front-Cover Texts being ``PolyORB User's Guide'', and with no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

About This Guide
****************

This guide describes the use of PolyORB, a middleware that enables the construction of Ada 95 distributed applications.

It describes the features of the middleware and related APIs and tools, and details how to use them to build Ada 95 applications.

What This Guide Contains
========================

This guide contains the following chapters:

  * Introduction to PolyORB provides a brief description of middleware and PolyORB's architecture.

  * Installation details how to configure and install PolyORB on your system.

  * Overview of PolyORB personalities enumerates the different personalities, or distribution mechanisms, PolyORB provides.

  * Building an application with PolyORB presents the different steps to build a distributed application using PolyORB.

  * Tasking model in PolyORB details the use of tasking constructs within PolyORB.

  * CORBA describes PolyORB's implementation of OMG's CORBA.

  * RT-CORBA describes PolyORB's implementation of RT-CORBA, the real-time extensions of OMG's CORBA.

  * DSA describes PolyORB's implementation of the Ada Distributed System Annex.

  * MOMA describes PolyORB's implementation of MOMA, the Message Oriented Middleware for Ada.

  * AWS describes the integration of the Ada Web Server (AWS) framework into PolyORB.

  * GIOP describes PolyORB's implementation of GIOP, the protocol defined as part of CORBA.

  * SOAP describes PolyORB's implementation of SOAP.

  * Tools describes PolyORB's tools.

  * Conformance to standards discusses the conformance of the PolyORB's personalities to the CORBA and SOAP standards.

  * References provides a list of useful references to complete this documentation.

  * GNU Free Documentation License contains the text of the license under which this document is being distributed.

Conventions
===========

Following are examples of the typographical and graphic conventions used in this guide:

  * Functions, utility program names, standard names, and classes.

  * Option flags

  * File Names, button names, and field names.

  * VARIABLES.

  * Emphasis.

  * [optional information or parameters]

  * Examples are described by text

          and then shown this way.

Commands that are entered by the user are preceded in this manual by the characters ``$ '' (dollar sign followed by space). If your system uses this sequence as a prompt, then the commands will appear exactly as you see them in the manual. If your system uses some other prompt, then the command will appear with the $ replaced by whatever prompt character you are using.

Full file names are shown with the ``/'' character as the directory separator; e.g., parent-dir/subdir/myfile.adb. If you are using GNAT on a Windows platform, please note that the ``\'' character should be used instead.

Introduction to PolyORB
***********************

Distributed applications and middleware
=======================================

PolyORB aims at providing a uniform solution to build distributed applications; relying either on industrial-strength middleware standards such as CORBA, the Distributed System Annex of Ada 95, distribution programming paradigms such as Web Services, Message Oriented Middleware (MOM), or to implement application-specific middleware.

Middleware provides a framework that hides the complex issues of distribution, and offers the programmer high-level abstractions that allow easy and transparent construction of distributed applications. A number of different standards exist for creating object-oriented distributed applications. These standards define two subsystems that enable interaction between application partitions:

  * the API seen by the developer's applicative objects;

  * the protocol used by the middleware environment to interact with other nodes in the distributed application.

Middleware implementations also offer programming guidelines as well as development tools to ease the construction of large heterogeneous distributed systems. Many issues typical to distributed programming may still arise: application architectural choice, configuration or deployment. Since there is no "one size fits all" architecture, choosing the adequate distribution middleware in its most appropriate configuration is a key design point that dramatically impacts the design and performance of an application.

Consequently, applications need to rapidly tailor middleware to the specific distribution model they require. A distribution model is defined by the combination of distribution mechanisms made available to the application. Common examples of such mechanisms are Remote Procedure Call (RPC), Distributed Objects or Message Passing. A distribution infrastructure or middleware refers to software that supports one (or several) distribution model, e.g.: OMG CORBA, Java Remote Method Invocation (RMI), the Distributed System Annex of Ada 95, Java Message Service (MOM).

PolyORB a generic middleware with an instance per distribution model
====================================================================

Typical middleware implementations for one platform support only one set of such interfaces, pre-defined configuration capabilities and cannot interoperate with other platforms. In addition to traditional middleware implementations, PolyORB proposes an original architecture to enable support for multiple interoperating distribution models in a uniform canvas.

PolyORB is a polymorphic, reusable infrastructure for building or prototyping new middleware adapted to specific application needs. It provides a set of components on top of which various instances can be elaborated. These instances (or personalities) are views on PolyORB facilities that are compliant to existing standards, either at the API level (application personality) or at the protocol level (protocol personality). These personalities are mutually exclusive views of the same architecture.

The decoupling of application and protocol personalities, and the support for multiple simultaneous personalities within the same running middleware, are key features required for the construction of interoperable distributed applications. This allows PolyORB to communicate with middleware that implement different distribution standards: PolyORB provides middleware-to-middleware interoperability (M2M).

PolyORB's modularity allows for easy extension and replacement of its core and personality components, in order to meet specific requirements. In this way, standard or application-specific personalities can be created in a streamlined process, from early stage prototyping to full-featured implementation. The PolyORB architecture also allows the automatic, just-in-time creation of proxies between incompatible environments.

You may find more information on PolyORB, including technical and scientific papers on PolyORB, on the project websites: http://libre.adacore.com/polyorb/ and http://polyorb.objectweb.org/.

Note: PolyORB is the project formerly known as DROOPI, a Distributed Reusable Object-Oriented Polymorphic Infrastructure

Installation
************

Supported Platforms
===================

PolyORB has been compiled and successfully tested on the following platforms:

  * FreeBSD

  * HP-UX

  * Linux

  * MacOS X

  * Solaris

  * Windows

Note: PolyORB should compile and run on every target for which GNAT and the GNAT.Sockets package are available.

Build requirements
==================

Ada 95 compiler: GNAT 5.02a1 (or later), GCC 4.0.2 (or later).

Optional:

  * XML/Ada (http://libre.adacore.com/xmlada/) if you want to build the SOAP protocol personality.

Note: per construction, the macro configure used to find your GNAT compiler looks first to the executables gnatgcc, then adagcc and finally to gcc to find out which Ada compiler to use. You should be very careful with your path and executables if you have multiple GNAT versions installed. See below explanations on the ADA environment variable if you need to override the default guess.

Build instructions
==================

To compile and install PolyORB, execute:

       % ./configure [some options]
       % make              (or gmake if your make is not GNU make)
       % make install      (ditto)

This will install files in standard locations.  If you want to choose another prefix than /usr/local, give configure a --prefix=whereveryouwant argument.

Note: at this time, you MUST use GNU make to compile this software.

Additional instructions for cross platforms
===========================================

The RANLIB environment variable must be set to the path of the cross ranlib prior to running configure with the appropriate --target option.

Only one PolyORB installation (native or cross) is currently possible with a given --prefix. If both a native and a cross installation are needed on the same machine, distinct prefixes must be used.

Building the documentation and PolyORB's examples
=================================================

PolyORB's documentation and examples are built separately.

After building PolyORB, simply run make in the examples (resp. docs) directory to build the examples (resp. the documentation). The build process will only build examples that correspond to the personalities you configured.

Note: you may also install PolyORB's documentation in standard location typing make install.

Build Options
-------------

Available options for the 'configure' script include:

  * --with-appli-perso="...": application personalities to build

     Available personalities: AWS, CORBA, DSA, MOMA

     e.g.   --with-appli-perso="corba moma" to build both the CORBA and MOMA personalities

  * --with-proto-perso="...": personalities to build

     Available personalities: GIOP, SOAP

     e.g.   --with-proto-perso="giop soap" to build both the GIOP and SOAP personalities

  * --with-corba-services="...": CORBA COS services to build

     Available services: event, ir, naming, notification, time

     e.g.  --with-corba-services="event naming" to build only COS Event and COS Naming.

     By default, only the CORBA and GIOP personalities are built, no CORBA Services are built.

  * --with-openssl: build SSL support and SSL dependent features, including the IIOP/SSLIOP personality

  * --help: list all options available

  * --enable-shared: build shared libraries.

  * --enable-debug:  enable debugging information generation and supplementary runtime checks. Note that this option has a significant space and time cost, and is not recommended for production use.

Compiler, Tools and Run-Time libraries Options
----------------------------------------------

The following environment variables can be used to override configure's guess at what compilers to use:

  * CC:  the C compiler

  * ADA: the Ada 95 compiler (e.g. gcc, gnatgcc or adagcc)

  * CXXCPP, CXXCPPFLAGS: the preprocessor used by idlac (only when setting up the CORBA application personality). CORBA specifications require this preprocessor to be compatible with the preprocessing rules defined in the C++ programming language specifications.

For example, if you have two versions of GNAT installed and available in your PATH, and configure picks the wrong one, you can indicate what compiler should be used with the following syntax:

       % ADA=/path/to/good/compiler/gcc ./configure [options]

PolyORB will be compiled with GNAT build host's configuration, including run-time library. You may override this setting using ADA_INCLUDE_PATH and ADA_OBJECTS_PATH environment variables. See GNAT User's Guide for more details.

You can add specific build options to GNAT using the EXTRA_GNATMAKE_FLAGS variable:

       % EXTRA_GNATMAKE_FLAGS=--RTS=rts-sjlj ./configure [options]

You can also pass compiler-only flags using the ADAFLAGS variable.

NOTE: Developers building PolyORB from the version control repository who need to rebuild the configure and Makefile.in files should use the script support/reconfig for this purpose. This should be done after each update from the repository. In addition to the requirements above, they will need autoconf 2.57 or newer, automake 1.6.3 or newer, and libtool 1.5.8 or newer.

Platform notes
==============

Solaris 2.8:

  * /usr/bin/sed and /usr/ucb/sed will silently chop long lines, and /usr/xpg4/bin/sed will enter an endless loop while processing PolyORB files. GNU sed is required to configure and build PolyORB.

  * /usr/ucb/tr does not handle control character escape sequences: it cannot be used to recompute dependencies ('make depend'); /usr/bin/tr or /usr/xpg4/bin/tr must be used.

Tru64 5.1A:

The default maximal data segment size may not be sufficient to compile PolyORB. If a GNAT heap exhausted error message occurs during build, try raising this limit using:

     ulimit -d unlimited

AIX 5.2:

PolyORB must be compiled with the -mminimal-toc compiler switch. This can be achieved by setting the following values in the environment at configure time:

     ADAFLAGS="-g -O2 -mminimal-toc"
     CFLAGS="-g -O2 -mminimal-toc"

HP-UX 11.00:

The version of install(1) from /opt/imake/bin on HP-UX is not suitable for installing PolyORB. Make sure that /opt/imake/bin is not on the PATH when building and installing PolyORB.

Overview of PolyORB personalities
*********************************

A personality is an instantiation of specific PolyORB components. It provides the mechanisms specified by a distribution model, e.g. an API, a code generator or a protocol stack.

This section provides a brief overview of existing personalities.

Note: some of these personalities are available only through PolyORB's repository.

Application personalities
=========================

Application personalities constitute the adaptation layer between application components and middleware. They provide APIs and/or code generator to register application entities with PolyORB's core, and interoperate with the core to allow the exchange of requests with remote entities.

CORBA
-----

CORBA is OMG specification of a Distributed Object Computing (DOC) distribution model ([OMG04]). It is now a well-known and well-established specification, used in a wide range of industrial applications.

PolyORB provides a CORBA-compatible implementation based on mapping of the IDL language version 1.2 described in [OMG01] and CORBA core specifications. PolyORB also proposes an implementation of various additional specifications described by the OMG, including COS Services : COS Naming, Notification, Event, Time, additional specifications; RT-CORBA, PortableInterceptors, DynamicAny.

Distributed System Annex of Ada (DSA)
-------------------------------------

The Distributed System Annex of Ada (DSA) [ISO95] is a normative specification part of the language. It describes remote invocation schemes applied to most language constructs.

Message Oriented Middleware for Ada (MOMA)
------------------------------------------

MOMA (Message Oriented Middleware for Ada) provides message passing mechanisms. It is an Ada adaptation of Sun's Java Message Service (JMS) [SUN99], a standardized API for common message passing models.

Ada Web Server (AWS)
--------------------

The Web Server personality provides the same API as the Ada Web Server project (AWS) [Obr03]. It allows for the implementation of web services, web server applications, or classical web pages. AWS-based servers allow the programmer to directly interact with incoming or outgoing HTTP and SOAP requests.

Protocol personalities
======================

Protocol personalities handle the mapping of requests (representing interactions between application entities) onto messages exchanged through a communication network, according to a specific protocol.

GIOP
----

GIOP is the transport layer of the CORBA specifications. GIOP is a generic protocol. This personality implements GIOP versions from 1.0 to 1.2 along with the CDR representation scheme to map data types between the neutral core layer and CDR streams. It also provides the following dedicated instances:

  * IIOP supports synchronous request semantics over TCP/IP,

  * IIOP/SSIOP supports synchronous request semantics using SSL sockets,

  * MIOP instantiation of GIOP enables group communication over IP multicast,

  * DIOP relies on UDP/IP communications to transmit one-way requests only.

SOAP
----

The SOAP protocol [W3C03] enables the exchange of structured and typed information between peers. It is a self-describing XML document [W3C03] that defines both its data and semantics. Basically, SOAP with HTTP bindings is used as a communication protocol for Web Services.

Building an application with PolyORB
************************************

Compile-time configuration
==========================

The user may configure some elements of a PolyORB application at compile-time.

Tasking run-times
-----------------

PolyORB provides different tasking run-times. The user may select the most appropriate one, depending on its application requirements. The tasking run-times determine the constructs PolyORB may use for its internal synchronizations.

  * No_Tasking: There is no dependency on the Ada tasking run-time, middleware is mono-task.

  * Full_Tasking: Middleware uses Ada tasking constructs, middleware can be configured for multi-tasking.

  * Ravenscar : Middleware uses Ada tasking constructs, with the limitations of the Ravenscar profile [DB98].  Middleware can be configured for multi-tasking.

See Tasking model in PolyORB for more information on this point.

Middleware tasking policies
---------------------------

PolyORB provides several tasking policies. A tasking policy defines how tasks are used by the middleware to process incoming requests.

  * No_Tasking: There is only one task in middleware, processing all requests.

  * Thread_Per_Session: One task monitors communication entities. One task is spawned for each active connection. This task handles all incoming requests on this connection.

  * Thread_Per_Request: One task monitors communication entities. One task is spawned for each incoming requests.

  * Thread_Pool: A set of tasks cooperate to handle all incoming requests.

See Tasking model in PolyORB for more information on this point.

Sample files
------------

PolyORB proposes a set of pre-defined setup packages. You must with one of them in your application node to activate the corresponding setup.

  * PolyORB.Setup.Client: a client node, without tasking enabled, configured to use all protocol personalities build with PolyORB.

  * PolyORB.Setup.Ravenscar_TP_Server: a server node, with tasking enabled, configured to use all protocol personalities build with PolyORB. Middleware tasking runtime follow Ravenscar's profile restrictions. Middleware tasking policies is Thread_Pool.

  * PolyORB.Setup.Thread_Per_Request_Server: a server node, with tasking enabled, configured to use all protocol personalities build with PolyORB. Middleware tasking policies is Thread_Per_Request.

  * PolyORB.Setup.Thread_Per_Session_Server: a server node, with tasking enabled, configured to use all protocol personalities build with PolyORB. Middleware tasking policies is Thread_Per_Session.

  * PolyORB.Setup.Thread_Pool_Server: a server node, with tasking enabled, configured to use all protocol personalities build with PolyORB. Middleware tasking policies is Thread_Pool.

To enforce one of these configurations, add a dependency on one of these packages. The elaboration of the application (based on Ada rules) and the initialization of the partition (based on the application personalities mechanisms) will set up properly your application.

Run-time configuration
======================

The user may configure some elements of a PolyORB application at run-time.

Using the default configurations provided by PolyORB, the parameters are read in the following order: command line, environment variables, configuration file. PolyORB will use the first value that matches the searched parameter.

Using a configuration file
--------------------------

A configuration file may be used to configure a PolyORB node. A sample configuration file may be found in src/polyorb.conf.

The syntax of the configuration file is:

  * empty lines and lines that have a '#' in column 1 are ignored;

  * sections can be started by lines of the form [ SECTION-NAME ']';

  * variable assignments can be performed by lines of the form VARIABLE-NAME '=' VALUE.

     Any variable assignment is local to a section.

     Assignments that occur before the first section declaration are relative to section [environment].  Section and variable names are case sensitive.

     Furthermore, each time a resolved in that section value starts with "file:", the contents of the file is used instead.

Default search path for polyorb.conf is current directory. Environment variable POLYORB_CONF may be used to set up information on configuration file.

PolyORB's configuration file allows the user to

 1. enable/disable the output of debug information

 2. set up default reference on naming service

 3. select the default protocol personality

 4. set up each protocol personality

The configuration file is read once when running a node, during elaboration.

Using environment variables
---------------------------

A variable Var.Iable in section [Sec] can be overridden by setting environment variable "POLYORB_SEC_VAR_IABLE".

Using the command line
----------------------

PolyORB allows to set up configuration variables on the command line. The syntax is close to the one described in configuration files A variable Var.Iable in section [Sec] can be overridden with flag --polyorb-<sec>-<var>-<iable>[=<value>].

Setting up protocol personalities
=================================

PolyORB allows the user to activate some of the available protocol personalities and to set up preferred protocol. Protocol-specific parameters are defined in their respective sections.

Activating/Deactivating protocol personalities
----------------------------------------------

Protocol activation is controlled by PolyORB's configuration file.

The section [access_points] control the initialization of access points. An access point is a node entry point that may serve incoming requests.

     [access_points]
     soap=enable
     iiop=enable
     diop=disable
     uipmc=disable

This example activates SOAP and IIOP, deactivates DIOP and MIOP.

The section [modules] controls the activation/deactivation of some modules within PolyORB. It is used to enable bindings to remote entities.

     [modules]
     binding_data.soap=enable
     binding_data.iiop=enable
     binding_data.diop=disable
     binding_data.uipmc=disable

This example enables the creation of bindings to remote objects using SOAP or IIOP. Objects cannot be reached using DIOP or UIPMC.

Note: by default, all configured personalities are activated.

Configuring protocol personality preferences
--------------------------------------------

The user may affect a preference to each protocol personality. The protocol with the higher preference will be selected among possible protocols to send a request to a remote node.

See polyorb.binding_data.<protocol>.preference in section [protocol] to set up protocol's preference.

Possible protocols are defined as the protocols available on the remote node, as advertised in its object reference.  IOR or corbaloc references may support multiple protocols, URI only support one protocol.

Each protocol supports a variety of configuration parameters, please refer to the protocols' sections for more details.

Activating debug information
============================

To activate the output of debug information, you must first configure and compile PolyORB with debug activate, see help on --enable-debug flag in Installation.

To output debug information on a selected package, create a configuration file with a [log] section and the name of the packages on which you want debug information:

     # Sample configuration file, output debug for PolyORB.A_Package
     [log]
     polyorb.a_package=debug

Note that some packages may not provide such information. See sample configuration file the complete list of packages that provide debug.

Tracing exceptions
==================

To trace exception propagation in PolyORB's source code, it is necessary to:

 1. compile PolyORB with debug activated,

 2. activate debug information on package PolyORB.Exceptions.

polyorb-config
==============

polyorb-config returns path and library information on PolyORB's installation.

     NAME
            polyorb-config  - script to get information about the installed version
            of PolyORB.

     SYNOPSIS
            polyorb-config [--prefix[=DIR]] [--exec-prefix[=DIR]] [--version|-v]
            [--config] [--libs] [--cflags] [--idls] [--help]

     DESCRIPTION
            polyorb-config  is  a  tool  that is used to determine the compiler and
            linker flags that should be used to compile and link programs that  use
            PolyORB.

     OPTIONS
            polyorb-config accepts the following options:

            --prefix[=DIR]
                     Output the directory in which PolyORB architecture-independent
                    files are installed, or set this directory to DIR.

            --exec-prefix[=DIR]
                     Output the directory in which  PolyORB  architecture-dependent
                    files are installed, or set this directory to DIR.

            --version
                    Print  the  currently installed version of PolyORB on the stan-
                    dard output.

            --config
                    Print the configuration of the currently installed  version  of
                    PolyORB on the standard output.

            --libs  Print  the  linker  flags  that are necessary to link a PolyORB
                    program.

            --cflags
                    Print the compiler flags that are necessary to compile a  Poly-
                    ORB program.

            --idls
                    Output flags to set up path to CORBA's IDL for idlac.

            --with-appli-perso=P,P,P
                    Restrict output to only those flags relevant to the listed
                    applicative personalities.

            --with-proto-perso=P,P,P
                    Restrict output to only those flags relevant to the listed
                    protocol personalities.

            --with-corba-services=S,S,S
                   Restrict output to only those flags relevant to the listed
                   services.

            --help  Print help message.

Tasking model in PolyORB
************************

PolyORB Tasking runtimes
========================

PolyORB may use three different tasking runtimes to manage and synchronize tasks, if any. Tasking runtimes capabilities are defined in the Ada reference manual [ISO95] and the next revision of this standard (Ada0Y).

The choice of a specific tasking runtime is a compile-time parameter, Tasking run-times for more details on their configuration.

Full tasking runtime
--------------------

Full tasking runtime refers to configuration in which there are some dependencies on the tasking constructs defined in chapter 9 of [ISO95]. It makes use of all capabilities defined in this section to manage and synchronize tasks.

In this configuration, a PolyORB application must be compiled and linked with a tasking-capable Ada runtime.

No tasking runtime
------------------

No tasking runtime refers to configuration in which there is no semantic dependency on tasking constructs. Thus, no tasking is required.

In this configuration, a PolyORB application may be compiled and linked with a tasking-capable Ada runtime or a no-tasking Ada runtime.

Ravenscar tasking runtime
-------------------------

Ravenscar tasking runtime refers to configuration in which tasking constructs are compliant with the Ravenscar tasking restricted profile.

In this configuration, a PolyORB application may be compiled and linked with a tasking-capable Ada runtime or a Ravenscar Ada runtime.

To configure tasking constructs used by PolyORB, one must instanciate the PolyORB.Setup.Tasking.Ravenscar package to setup tasks and protected objects used by PolyORB core.

     [file polyorb-setup-tasking-ravenscar.texi not included]

PolyORB ORB Tasking policies
============================

PolyORB ORB Tasking policies control the creation of tasks to process all middleware internal jobs, e.g. request processing, I/O monitoring.

Note: there is a dependency between ORB Tasking policies, and the run-time used

No Tasking
----------

Under the No Tasking ORB policy, no task are created within the middleware instance: it uses the environment task to process all jobs. Note that this policy is not thread-safe and is compatible with the No tasking runtime only.

Thread Pool
-----------

Under the Thread Pool ORB policy, the middleware creates a pool of thread during the initialization of PolyORB. This pool processes all jobs. The number of tasks in the thread pool can be configured by three parameters in the [tasking] configuration section.

  * min_spare_threads indicates the number of tasks created at startup.

  * max_spare_threads is a ceiling. When a remote subprogram call is completed, its anonymous task is deallocated if the number of tasks already in the pool is greater than the ceiling. If not, then the task is queued in the pool.

  * max_threads indicates the maximum number of tasks in the pool.

See PolyORB Tasking configuration, for more information on how to configure the number of tasks in the thread pool.

Thread Per Session
------------------

Under the Thread Per Session ORB policy, the middleware creates one task when a new session (one active connection) is opened. The task is finalized when the session is closed.

Thread Per Request
------------------

Under the Thread Per Request ORB policy, the middleware creates one task per incoming request. The task is finalized when the request is completed.

PolyORB Tasking configuration
=============================

The following parameters allow the user to set up some of the tasking parameters.

     ###############################################################################
     # Parameters for tasking
     #

     [tasking]
     # Default storage size for all threads spawned by PolyORB
     #storage_size=262144

     # Number of threads by Thread Pool tasking policy
     #min_spare_threads=4
     #max_spare_threads=4
     #max_threads=4

PolyORB ORB Controller policies
===============================

The PolyORB ORB Controller policies are responsible for the management of the global state of the middleware: they assign middleware internal jobs, or I/Os monitoring to middleware tasks.

ORB Controller policies grant access to middleware internals and affect one action for each middleware task. They ensure that all tasks work concurrently in a thread-safe manner.

No Tasking
----------

The No Tasking ORB Controller policy is dedicated to no tasking middleware configurations; the middleware task executes the following loop: process internal jobs, then monitor I/Os.

Workers
-------

The Workers ORB Controller policy is a simple controller policy: all tasks are equal, they may alternatively and randomly process requests or wait for I/O sources.

Note: it is the default configuration provided by PolyORB sample setup files, see Sample files.

Half Sync/Half Async
--------------------

The Half Sync/Half Async ORB Controller policy implements the ``Half Sync/Half Async'' design pattern: it discriminates between one thread dedicated to I/O monitoring that queue middleware jobs; another pool of threads dequeue jobs and process them.

Note: this pattern is well-suited to process computation-intensive requests.

Leader/Followers
----------------

The Leader/Followers ORB Controller policy implements the ``Leader/Followers '' design pattern: multiple tasks take turns to monitor I/O sources and then process requests that occur on the event sources.

Note: this pattern is adapted to process a lot of light requests.

PolyORB ORB Controller configuration
====================================

The following parameters allow the user to set up parameters for ORB Controllers.

     ###############################################################################
     # Parameters for ORB Controllers
     #

     [orb_controller]
     # Interval between two polling actions on one monitor
     #polyorb.orb_controller.polling_interval=0

     # Timeout when polling on one monitor
     #polyorb.orb_controller.polling_timeout=0

CORBA
*****

What you should know before Reading this section
================================================

This section assumes that the reader is familiar with the CORBA specifications described in [OMG04] and the IDL-to-Ada mapping defined in [OMG01].

Installing CORBA application personality
========================================

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

To build the CORBA application personality, see Installation.

Usage of idlac
==============

idlac is PolyORB's IDL-to-Ada 95 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 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.

Resolving names in a CORBA application
======================================

PolyORB implements the CORBA COS Naming service.

po_cos_naming
-------------

po_cos_naming is a stand alone server that supports CORBA COS Naming specification. When launched, it returns its IOR and corbaloc that 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.

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 -ORB InitRef NamingService=<IOR> or -ORB InitRef 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.

Using the COS Naming
--------------------

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

The CORBA Interface Repository
==============================

PolyORB implements the CORBA Interface Repository.

po_ir
-----

po_ir is a stand alone server that supports the CORBA Interface Repository. When launched, it returns its IOR and corbaloc that 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.

Using the Interface Repository
------------------------------

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

Building a CORBA application with PolyORB
=========================================

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 examples/corba/echo directory in PolyORB distribution. This applications uses only basic elements of CORBA.

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

 1. IDL definition of an echo object

 2. Implementation code for the echo object

 3. Code for client and server nodes

IDL definition of an echo object
................................

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

     [file echo.texi not included]

Implementation code for the echo object
.......................................

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

     [file echo-impl.texi not included]
     [file echo-impl-body.texi not included]

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

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 setup 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 object. It is a no tasking client. Reference to object is built from stringified reference (or IOR), which is passed through command line.

          [file client-body.texi not included]

  * Server code setups a no tasking node. Object is registered to the RootPOA. Then an IOR reference is built to enable interaction with other nodes.

          [file server-body.texi not included]

Compilation and execution
.........................

To compile this demo,

 1. Process the IDL file with idlac

           $ idlac echo.idl

 2. Compile the client node

           $ gnatmake client.adb `polyorb-config`

 3. 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, an hexadecimal string with the <IOR:> prefix.

          $ ./server
          Loading configuration from polyorb.conf
          No polyorb.conf configuration file.
          'IOR:01534f410d00000049444c3[..]'

  * run client, passing the complete IOR on the command line

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

Other examples
--------------

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

  * all_functions tests CORBA parameters passing mode (in, out, ..);

  * all_types tests CORBA types;

  * echo is a simple CORBA demo;

  * random is a random number generator;

  * send tests MIOP specific API.

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).

Configuring PolyORB
-------------------

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

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.

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.

Implementation Notes
====================

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

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.

Implementation of CORBA specifications
--------------------------------------

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

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

Additions to the CORBA specifications
-------------------------------------

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

Besides, 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).

Interface repository
--------------------

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

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_domaing_manager entry in the [corba] section in your configuration file, policy_domaing_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.

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, idlac 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.

Internals packages
------------------

PolyORB sometimes declare internals types and routines inside CORBA packages. In this case, 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.

PolyORB's specific APIs
=======================

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

  * PolyORB.CORBA_P.CORBALOC:

     This package defines a helper function to build a corbaloc stringified reference from a CORBA object reference.

  * PolyORB.CORBA_P.Naming_Tools:

     This package defines helper functions to ease interaction with CORBA COS Naming.

  * PolyORB.CORBA_P.Server_Tools:

     This package defines helper functions to ease set up of a simple CORBA Server.

PolyORB.CORBA_P.CORBALOC
------------------------

     [file polyorb-corba_p-corbaloc.texi not included]

PolyORB.CORBA_P.Naming_Tools
----------------------------

     [file polyorb-corba_p-naming_tools.texi not included]

PolyORB.CORBA_P.Server_Tools
----------------------------

     [file polyorb-corba_p-server_tools.texi not included]

RT-CORBA
********

What you should know before Reading this section
================================================

This section assumes that the reader is familiar with the Real-Time CORBA specifications described in [OMG02a] and [OMG03].

Installing RT-CORBA
===================

The RT-CORBA library is installed as part of the installation of the CORBA personality. Note that you may have to select specific run-time options to enable full compliance with RT-CORBA specifications and ensure real time behavior.

Configuring RT-CORBA
====================

This section details how to configure your application to use the RT-CORBA library.

PolyORB.RTCORBA_P.Setup
-----------------------

RT-CORBA specifications mandates the implementation provides a mechanism to set up some of its internals.

The package PolyORB.RTCORBA_P.Setup provides an API to set up the PriorityMapping and PriorityTransform objects.

     [file polyorb-rtcorba_p-setup.texi not included]

RTCORBA.PriorityMapping
=======================

PolyORB provides different implementations of this specification:

  * RTCORBA.PriorityMapping.Direct maps CORBA priorities directly to native priorities. If the CORBA priority is not in System.Priority'Range, then the mapping is not possible.

  * RTCORBA.PriorityMapping.Linear maps each individual native priority to a contiguous range of CORBA priorities, so that the complete CORBA priority range is used up for the mapping. See rtcorba-prioritymapping-linear.adb for more details.

RTCosScheduling Service
=======================

Overview
--------

PolyORB provides an implementation of the RTCosScheduling service defined in [OMG02a].

PolyORB uses some permission stated in the specifications to allow for an easy configuration of ClientScheduler and ServerScheduler, defined in the following sections.

Additional information on the use of the API may be found in the RTCosScheduling example in examples/corba/rtcorba/rtcosscheduling.

RTCosScheduling::ClientScheduler
--------------------------------

Client side activities are defined in a configuration file, than can be loaded using RTCosScheduling.ClientScheduler.Impl.Load_Configuration_File

On the client side, the user can set up

  * current task priority, using registered PriorityMapping object.

This file has the following syntax, derived from PolyORB configuration files syntax:

     # Name of the activity
     [activity activity1]

     # Activity priority, in RTCORBA.Priority'Range
     priority=10000

In this example, activity activity1 is defined with priority 10'000.

RTCosScheduling::ServerScheduler
--------------------------------

Server side POAs and objects are defined in a configuration file, than can be loaded using RTCosScheduling.ClientScheduler.Impl.Load_Configuration_File

On the server side, the user can set up

  * object priority, using registered PriorityMapping object.

  * all RT-CORBA-specific POA configuration parameters:

This file has the following syntax, derived from PolyORB configuration files syntax:

     # Name of the object
     [object object1]

     # Object priority, in RTCORBA.Priority'Range
     priority=10000

In this example, object object1 is defined with priority 10'000.

     # Name of the POA
     [poa poa1]

     # PriorityModelPolicy for POA
     priority_model=CLIENT_PROPAGATED
     default_priority=0 # not meaningful for CLIENT_PROPAGATED

     # Threadpools attached to POA
     threadpool_id=1

     # Name of the POA
     [poa poa2]

     # PriorityModelPolicy for POA
     priority_model=SERVER_DECLARED
     default_priority=40

     # Threadpools attached to POA
     threadpool_id=2

     # Name of the POA
     [poa poa3]

     # POA with no defined policies

In this example, Two POAs are defined: POA poa1 will use the CLIENT_PROPAGATED PriorityModel Policy, default value is not meaningful for this configuration, poa1 will use the Threadpool #1; POA poa2 will use the SERVER_DECLARED PriorityModel Policy, default server priority is 40, poa2 will use the Threadpool #2. Note that both policies are optional and can be omitted.

Ada Distributed System Annex (DSA)
**********************************

The documentation of this personality will appear in a future revision of PolyORB.

MOMA
****

What you should know before Reading this section
================================================

This section assumes that the reader is familiar with the JMS specifications described in [SUN99]. MOMA is a thick adaptation of the JMS specification to the Ada programming language. It preserves most of its concepts.

Installing MOMA application personality
=======================================

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

To build the MOMA application personality, see Installation.

Package hierarchy
=================

Packages installed in $INSTALL_DIR/include/polyorb/moma hold the MOMA API. MOMA is built around two distinct set of packages:

 1. MOMA.* hold the public MOMA library, all the constructs the user may use.

 2. POLYORB.MOMA_P.* hold the private MOMA library, these packages shall not be used when building your application.

Ada Web Server (AWS)
********************

The documentation of this personality will appear in a future revision of PolyORB.

GIOP
****

Installing GIOP protocol personality
====================================

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

To enable the configuration of the GIOP protocol personality, see Installation.

GIOP Instances
==============

GIOP is a generic protocol that can be instantiated for multiple transport stacks. PolyORB proposes three different instances.

IIOP
----

Internet Inter-ORB Protocol (IIOP) is the default protocol defined by the CORBA specifications. It is a TCP/IP, IPv4, based protocol that supports the full semantics of CORBA requests.

SSLIOP
------

The SSLIOP protocol provides transport layer security for transmitted requests.  Its provides encryption of GIOP requests.

To build the SSLIOP, it is required to activate SSL-related features when building PolyORB. See Installation for more details.

Enabling security is completely transparent to a preexisting application, it is also possible to phase in secure communications by allowing incoming requests which are unsecured.

DIOP
----

Datagram Inter-ORB Protocol (DIOP) is a specialization of GIOP for the UDP/IP protocol stack. It supports only asynchronous (oneway) requests.

This protocol is specific to PolyORB. DIOP 1.0 is mapping of GIOP on top of UDP/IP. DIOP 1.0 uses GIOP 1.2 message format.

MIOP
----

Unreliable Multicast Inter-ORB Protocol (MIOP) [OMG02b] is a specialization of GIOP for IP/multicast protocol stack. It supports only asynchronous (oneway) requests.

Configuring the GIOP personality
================================

GIOP personality is configured using a configuration file. See Using a configuration file for more details.

Here is a summary of available parameters for each instance of GIOP.

Common configuration parameters
-------------------------------

This section details configuration parameters common to all GIOP instances.

     ###############################################################################
     # GIOP parameters
     #

     [giop]

     ###############################################################
     # Native code sets
     #
     # Available char data code sets:
     #   16#00010001#   ISO 8859-1:1987; Latin Alphabet No. 1
     #   16#05010001#   X/Open UTF-8; UCS Transformation Format 8 (UTF-8)
     #
     # Available wchar data code sets:
     #   16#00010100#   ISO/IEC 10646-1:1993; UCS-2, Level 1
     #   16#00010109#   ISO/IEC 10646-1:1993;
     #                                UTF-16, UCS Transformation Format 16-bit form
     #
     #giop.native_char_code_set=16#00010001#
     #giop.native_wchar_code_set=16#00010100#
     #
     # The following parameters force the inclusion of fallback code sets
     # as supported conversion code sets. This is required to enable
     # interoperability with ORBs whose code sets negotiation support is
     # broken. See PolyORB's Users Guide for additional information.
     #
     #giop.add_char_fallback_code_set=false
     #giop.add_wchar_fallback_code_set=false

IIOP Configuration Parameters
-----------------------------

     ###############################################################################
     # IIOP parameters
     #

     [iiop]

     ###############################################################
     # IIOP Global Settings

     # Preference level for IIOP
     #polyorb.binding_data.iiop.preference=0

     # IIOP's default address
     #polyorb.protocols.iiop.default_addr=127.0.0.1

     # IIOP's default port
     #polyorb.protocols.iiop.default_port=2809

     # IIOP's alternate addresses
     #polyorb.protocols.iiop.alternate_listen_addresses=127.0.0.1:2810 127.0.0.1:2820

     # Default GIOP/IIOP Version
     #polyorb.protocols.iiop.giop.default_version.major=1
     #polyorb.protocols.iiop.giop.default_version.minor=2

     ###############################################################
     # IIOP 1.2 specific parameters

     # Set to True to enable IIOP 1.2
     #polyorb.protocols.iiop.giop.1.2.enable=true

     # Set to True to send a locate message prior to the request
     #polyorb.protocols.iiop.giop.1.2.locate_then_request=true

     # Maximum message size before fragmenting request
     #polyorb.protocols.iiop.giop.1.2.max_message_size=1000

     ###############################################################
     # IIOP 1.1 specific parameters

     # Set to True to enable IIOP 1.1
     #polyorb.protocols.iiop.giop.1.1.enable=true

     # Set to True to send a locate message prior to the request
     #polyorb.protocols.iiop.giop.1.1.locate_then_request=true

     # Maximum message size before fragmenting request
     #polyorb.protocols.iiop.giop.1.1.max_message_size=1000

     ###############################################################
     # IIOP 1.0 specific parameters

     # Set to True to enable IIOP 1.0
     #polyorb.protocols.iiop.giop.1.0.enable=true

     # Set to True to send a locate message prior to the request
     #polyorb.protocols.iiop.giop.1.0.locate_then_request=true

SSLIOP Configuration Parameters
-------------------------------

Specific configuration for SSLIOP
.................................

For now PolyORB may support SSLIOP only if all others protocol personalities are disabled and IIOP unprotected invocation also disabled. Thus, polyorb.conf file should have the following contents:

     [access_points]
     srp=disable
     soap=disable
     diop=disable
     uipmc=disable
     iiop=enable
     iiop.ssliop=enable

     [modules]
     binding_data.srp=disable
     binding_data.soap=disable
     binding_data.diop=disable
     binding_data.uipmc=disable
     binding_data.iiop=enable
     binding_data.iiop.ssliop=enable

     [ssliop]
     polyorb.protocols.ssliop.disable_unprotected_invocations=true

Ciphers name
............

PolyORB's SSLIOP uses the OpenSSL library to support all recommended by CORBA 3.0.3 ciphers. OpenSSL library uses specific names for ciphers. The table below contains CORBA recommended ciphers names and its OpenSSL equivalents:

CORBA recommended ciphers                 OpenSSL equivalent
TLS_RSA_WITH_RC4_128_MD5                  RC4-MD5
SSL_RSA_WITH_RC4_128_MD5                  RC4-MD5
TLS_DHE_DSS_WITH_DES_CBC_SHA              EDH-DSS-CBC-SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA              EDH-DSS-CBC-SHA
TLS_RSA_EXPORT_WITH_RC4_40_MD5            EXP-RC4-MD5
SSL_RSA_EXPORT_WITH_RC4_40_MD5            EXP-RC4-MD5
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA     EXP-EDH-DSS-DES-CBC-SHA
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA     EXP-EDH-DSS-DES-CBC-SHA

SSLIOP Parameters
.................

     ###############################################################################
     # SSLIOP parameters
     #

     [ssliop]

     ###############################################################
     # SSLIOP Global Settings

     # SSLIOP's default port
     #polyorb.protocols.ssliop.default_port=2810
     # If no SSLIOP default address is provide, PolyORB reuses IIOP's
     # address

     # Private Key file name
     #polyorb.protocols.ssliop.privatekeyfile=privkey.pem

     # Certificate file name
     #polyorb.protocols.ssliop.certificatefile=cert.pem

     # Trusted CA certificates file
     #polyorb.protocols.ssliop.cafile=cacert.pem

     # Trusted CA certificates path
     #polyorb.protocols.ssliop.capath=demoCA/certs

     # Disable unprotected invocations
     #polyorb.protocols.ssliop.disable_unprotected_invocations=true

     ###############################################################
     # Peer certificate verification mode

     # Verify peer certificate
     #polyorb.protocols.ssliop.verify=false

     # Fail if client did not return certificate. (server side option)
     #polyorb.protocols.ssliop.verify_fail_if_no_peer_cert=false

     # Request client certificate only once. (server side option)
     #polyorb.protocols.ssliop.verify_client_once=false

DIOP Configuration Parameters
-----------------------------

     ###############################################################
     # DIOP Global Settings

     # Preference level for DIOP
     #polyorb.binding_data.diop.preference=0

     # DIOP's default port
     #polyorb.protocols.diop.default_port=12345

     # Default GIOP/DIOP Version
     #polyorb.protocols.diop.giop.default_version.major=1
     #polyorb.protocols.diop.giop.default_version.minor=2

     ###############################################################
     # DIOP 1.2 specific parameters

     # Set to True to enable DIOP 1.2
     #polyorb.protocols.diop.giop.1.2.enable=true

     # Maximum message size
     #polyorb.protocols.diop.giop.1.2.max_message_size=1000

     ###############################################################
     # DIOP 1.1 specific parameters

     # Set to True to enable DIOP 1.1
     #polyorb.protocols.diop.giop.1.1.enable=true

     # Maximum message size
     #polyorb.protocols.diop.giop.1.1.max_message_size=1000

     ###############################################################
     # DIOP 1.0 specific parameters

     # Set to True to enable DIOP 1.0
     #polyorb.protocols.diop.giop.1.0.enable=true

MIOP Configuration Parameters
-----------------------------

     ###############################################################################
     # MIOP parameters
     #

     [miop]

     ###############################################################
     # MIOP Global Settings

     # Preference level for MIOP
     #polyorb.binding_data.uipmc.preference=0

     # Maximum message size
     #polyorb.miop.max_message_size=6000

     # Time To Leave parameter
     #polyorb.miop.ttl=15

     # Multicast address to use
     #polyorb.miop.multicast_addr=239.239.239.18

     # Multicast port to use
     #polyorb.miop.multicast_port=5678

     # Set to True to enable MIOP
     #polyorb.protocols.miop.giop.1.2.enable=false

     # Maximum message size
     #polyorb.protocols.miop.giop.1.2.max_message_size=1000

Code sets
=========

This sections details the various steps required to add the support for new character code sets in PolyORB's GIOP personality. Please, refer to CORBA specifications ([OMG04]), par. 13.10 for more details on this topic.

Adding support for new code sets
--------------------------------

PolyORB allows users to extend the set of supported native character code sets. Adding support for new character code set consists of the following steps:

 1. Developing sets of Converters - special objects which do marshalling/unmarshalling operations of character data. At least two Converters are required: for direct marshalling character data in native code set and for marshalling/unmarshalling character data in fallback character code set (UTF-8 for char data and UTF-16 for wchar data. Additional Converters may be developed for marshalling character data in conversion code set.

 2. Developing converter factory subprogram for each Converter.

 3. Registering native code set, its native and fallback converters and optional conversions char sets and it's converters.

Character data Converter
------------------------

Character data converter do direct marshalling/unmarshalling of character data (char or wchar - depending of Converter) into/from PolyORB's buffer. This allows to minimize speed penalty on character data marshalling.

Character data Converter for char data have the following API (from PolyORB.GIOP_P.Code_Sets.Converers package:

        type Converter is abstract tagged private;

        procedure Marshall
          (C      : Converter;
           Buffer : access Buffers.Buffer_Type;
           Data   : Types.Char;
           Error  : in out Errors.Error_Container)
           is abstract;

        procedure Marshall
          (C      : Converter;
           Buffer : access Buffers.Buffer_Type;
           Data   : Types.String;
           Error  : in out Errors.Error_Container)
           is abstract;

        procedure Unmarshall
          (C      : Converter;
           Buffer : access Buffers.Buffer_Type;
           Data   :    out Types.Char;
           Error  : in out Errors.Error_Container)
           is abstract;

        procedure Unmarshall
          (C      : Converter;
           Buffer : access Buffers.Buffer_Type;
           Data   :    out Types.String;
           Error  : in out Errors.Error_Container)
           is abstract;

Marshall subprograms do marshalling of one character or string of character into the buffer. Unmarshall subprograms do unmarshalling of one character or string of characters from the buffer.

Note: Depending on item size of character data (char/wchar) and GIOP version marshalling/unmarshalling algorithms may vary. For several situations marshalling of string is not equivalent to marshalling its length and marshalling one by one each string's character. Please refere to GIOP specifications for more details.

If marshalling/unmarshalling fails, subprograms must set Error parameter to corresponding error, usually Data_Conversion_E.

Note: We recommend to always use Data_Conversion_E error code with Minor status 1.

All Converters (native, fallback and conversion) have similar API.  Wchar data converters differ only in parameter type.

Converters factories
--------------------

To create new converters, PolyORB uses special factory subprograms with the following profile:

        function Factory return Converter_Access;

or

        function Factory return Wide_Converter_Access;

This function must allocate a new Converter and initialize its state.

Registering new code sets
-------------------------

Registering new native character data code sets begins from registering new native character data code sets and its native and fallback Converters. This is done using Register_Native_Code_Set:

        procedure Register_Native_Code_Set
          (Code_Set : Code_Set_Id;
           Native   : Converter_Factory;
           Fallback : Converter_Factory);

or

        procedure Register_Native_Code_Set
          (Code_Set : Code_Set_Id;
           Native   : Wide_Converter_Factory;
           Fallback : Wide_Converter_Factory);

If you have additional conversion code sets Converters you may register it by calling Register_Conversion_Code_Set subprogram:

        procedure Register_Conversion_Code_Set
          (Native     : Code_Set_Id;
           Conversion : Code_Set_Id;
           Factory    : Converter_Factory);

or

        procedure Register_Conversion_Code_Set
          (Native     : Code_Set_Id;
           Conversion : Code_Set_Id;
           Factory    : Wide_Converter_Factory);

Note: because of broken support of code sets negotiation in some ORB's it is recommend to recognize two boolean PolyORB's parameters:

     [giop]
     giop.add_char_fallback_code_set=false
     giop.add_wchar_fallback_code_set=false

and also register fallback Converter as conversion Converter if the corresponding parameter set to True.

Finally, define your prefferred native character data code sets by parameters (only integer code sets codes now supported):

     [giop]
     giop.native_char_code_set=16#00010001#
     giop.native_wchar_code_set=16#00010100#

SOAP
****

Installing SOAP protocol personality
====================================

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

To enable the configuration of the SOAP application personality, see Installation.

Configuring the SOAP personality
================================

SOAP personality is configured using a configuration file. See Using a configuration file for more details.

Here is a summary of available parameters for each instance of SOAP.

     ###############################################################################
     # SOAP parameters
     #

     [soap]

     ###############################################################
     # SOAP Global Settings

     # Preference level for SOAP
     #polyorb.binding_data.soap.preference=0

     # SOAP's default address
     #polyorb.protocols.soap.default_addr=127.0.0.1

     # SOAP's default port
     #polyorb.protocols.soap.default_port=8080

Tools
*****

po_catref
=========

po_catref is a utility for viewing components of a stringified reference (CORBA IOR, corbaloc or URI). Reference's component include reference to access an object through multiple protocols (e.g. CORBA IIOP, SOAP) and configuration parameters associated to a reference (e.g. GIOP Service Contexts).

     Usage:
            po_catref <stringified reference>

Note: po_catref can only process protocols PolyORB has been configured with.

po_dumpir
=========

po_dumpir is a utility for viewing the content of an instance of the CORBA Interface Repository.

     Usage:
            po_dumpir <stringified reference>

Note: po_dumpir will be compiled and installed only if the CORBA personality and the ir service is compiled. Please see Building an application with PolyORB for more details on how to set up PolyORB.

po_names
========

po_names is a stand-alone name server. It has an interface similar to CORBA COS Naming, without dragging any dependencies on CORBA mechanisms. This name server is to be used when the CORBA application personality is not required, e.g. with the DSA or MOMA application personalities.

Conformance to standards
************************

CORBA standards conformance
===========================

The OMG defines CORBA-compliant ORB as implementations of the CORBA specifications that supports CORBA Core and one mapping of CORBA's IDL.

Here is a summary of PolyORB's conformance issues with the latest CORBA specifications (revision 3.0, formal/02-06-01)

CORBA IDL-to-Ada mapping
------------------------

PolyORB supports the IDL-to-Ada specification [OMG01], with the following limitations in both CORBA API and the IDL-to-Ada compiler idlac:

  * no support for abstract interfaces, object-by-value, context data;

  * no support for CORBA Components;

  * implemented API may present some divergences with current mapping.

Note: generated code is constrained by the limitations of the Ada compiler used. Please refer to its documentation for more information.

CORBA Core
----------

This set encompasses chapters 1-11. Chapters 3 to 11 are normative.

  * Chapter 3 describes OMG IDL syntax and semantics. See CORBA IDL-to-Ada mapping for a description of non-implemented features;

  * Chapter 4 describes the ORB Interface.

     PolyORB partially supports this chapter.

  * Chapter 5 describes Value Type Semantics.

     PolyORB does not support this chapter.

  * Chapter 6 describes Abstract Interface Semantics.

     PolyORB does not support this chapter.

  * Chapter 7 describes Dynamic Invocation Interface (DII)

     PolyORB supports only the following methods: Create_Request, Invoke and Delete.

  * Chapter 8 describes Dynamic Skeleton Interface (DSI)

     PolyORB partially supports this chapter: this interface is fully implemented except for context data.

  * Chapter 9 describes Dynamic Management of Any Values

     PolyORB partially supports this chapter: this interface is fully implemented except for object references and value types.

  * Chapter 10 describes The Interface Repository

     PolyORB supports this chapter, except for the ExtValueDef interface, and all CORBA CCM related interfaces.

  * Chapter 11 describes The Portable Object Adapter

     PolyORB supports this chapter with the following limitations:

       * PERSISTENT policy is not supported;

       * USE_SERVANT_MANAGER policy is not supported;

       * support for SINGLE_THREAD policy is incomplete, reentrant calls may not work;

       * Wait_For_Completion and Etherealize_Objects are not taken into account in PortableServer.POAManager;

       * PortableServer.POAManagerFactory API is not implemented.

CORBA Interoperability
----------------------

This set encompasses chapters 12-16.

  * See CORBA-GIOP standards conformance for more information on this point.

CORBA Interworking
------------------

This set encompasses chapters 17-21.

  * Chapters 17 to 20 describe interoperability with Microsoft's COM/DCOM.

     PolyORB provides no support for these chapters.

  * Chapter 21 describes PortableInterceptor.

     PolyORB provides partial support for this chapter.

CORBA Quality Of Service
------------------------

This set encompasses chapters 22-24.

  * Chapter 22 describes CORBA Messaging

  * Chapter 23 describes Fault Tolerant CORBA

  * Chapter 24 describes Secure Interoperability.

PolyORB provides no support for these chapters.

CORBA COS Services
------------------

COS Services are specifications of high level services that are optional extensions to the CORBA specification. They provide helper packages to build distributed applications.  PolyORB implement the following COS Services:

  * COS Event and TypedEvent;

  * COS Naming, except for the NamingContextExt interface;

  * COS Notification;

  * COS Time;

CORBA Specialized services
--------------------------

PolyORB supports the following specialized services:

  * Unreliable Multicast (MIOP), proposed 1.0 specification [OMG02b].

  * RT-CORBA extensions, see RT-CORBA for more information on this point.

RT-CORBA standards conformance
==============================

RT-CORBA specifications relies on the CORBA application personality. It inherits all its issues, and implementations notes.

In addition, here is a list of issues with the implementation of RT-CORBA static [OMG02a] and dynamic scheduling [OMG03] specifications.

  * RT-CORBA static and dynamic scheduling (Chapter 2)

     Chapter 2 is common to these two specifications. It describes key mechanisms of RT-CORBA that are common to both specifications.

     PolyORB partially implements this chapter from section 2.1 up to section 2.10. PolyORB does not provide support for all connection-related policies.

     See implementation notes in the different package specifications for more details.

  * RT-CORBA static scheduling (Chapter 3)

     PolyORB supports this chapter.

  * RT-CORBA dynamic scheduling (Chapter 3)

     PolyORB does not support this chapter.

CORBA/GIOP standards conformance
================================

GIOP supports part of the CORBA Interoperability specification, from chapters 12 to 16 of CORBA specifications.

Chapter 12 defines general concepts about ORB interoperability. It defines interoperbility-compliant ORB as ORB that supports:

  * API that supports the construction of request-level inter-ORB bridges, Dynamic Invocation Interface, Dynamic Skeleton Interface and the object identity operations described in the Interface Repository. See CORBA standards conformance for more details.

  * IIOP protocol as defined in chapter 15.

Support for other components is optional.

  * Chapter 13 describes the ORB Interoperability Architecture.

     PolyORB fully supports this chapter.

  * Chapter 14 describes how to build Inter-ORB Bridges.

     PolyORB fully supports this chapter.

  * Chapter 15 describes the General Inter-ORB Protocol (GIOP).

     PolyORB supports GIOP version 1.0 to 1.2, the CDR representation scheme. Support for IOR and corbaloc addressing mechanisms is supported in CORBA personality, see CORBA for more details.

     PolyORB does not support the optional IIOP IOR Profile Components, Bi-directional GIOP, IIOP/SSL. PolyORB also does not support fragmentation in GIOP 1.1.

  * Chapter 16 describes the DCE ESIOP protocol.

     PolyORB does not support this optional chapter.

SOAP standards conformance
==========================

The documentation of the SOAP standards conformance of PolyORB will appear in a future revision of PolyORB.

References
**********

          [file polyorb_ug_ref.texi not included]

     [file gfdl.texi not included]