PolyORB User’s Guide

Robert Duff, Jérôme Hugues, Laurent Pautet, Thomas Quinot, Samuel Tardieu

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

• 1. Introduction to PolyORB
  • 1.1. Introduction to distributed systems
    • 1.1.1. Using OS Network Services
    • 1.1.2. Using a Middleware Environment
    • 1.1.3. Using a Distributed Language
  • 1.2. Distribution models and middleware standards
  • 1.3. The PolyORB generic middleware
• 2. Installation
  • 2.1. Supported Platforms
  • 2.2. Build requirements
  • 2.3. Build instructions
  • 2.4. Additional instructions for cross platforms
  • 2.5. Building the documentation and PolyORB’s examples
  • 2.6. Build Options
  • 2.7. Compiler, Tools and Run-Time libraries Options
  • 2.8. Platform notes
• 3. Overview of PolyORB personalities
  • 3.1. Application personalities
    • 3.1.1. CORBA
    • 3.1.2. Distributed Systems Annex of Ada (DSA)
    • 3.1.3. Message Oriented Middleware for Ada (MOMA)
  • 3.2. Protocol personalities
    • 3.2.1. GIOP
    • 3.2.2. SOAP
• 4. Building an application with PolyORB
  • 4.1. Compile-time configuration
    • 4.1.1. Tasking runtimes
    • 4.1.2. Middleware tasking policies
    • 4.1.3. Sample files
  • 4.2. Run-time configuration
    • 4.2.1. Using a configuration file
    • 4.2.2. Using environment variables
    • 4.2.3. Using the command line
    • 4.2.4. Using a source file
    • 4.2.5. Macros
  • 4.3. Setting up protocol personalities
    • 4.3.1. Activating/Deactivating protocol personalities
    • 4.3.2. Configuring protocol personality preferences
  • 4.4. Activating debugging traces
  • 4.5. Tracing exceptions
  • 4.6. polyorb.gpr
  • 4.7. polyorb-config
• 5. Tasking model in PolyORB
  • 5.1. PolyORB Tasking runtimes
    • 5.1.1. Full tasking runtime
    • 5.1.2. No tasking runtime
    • 5.1.3. Ravenscar tasking runtime
  • 5.2. PolyORB ORB Tasking policies
    • 5.2.1. No Tasking
    • 5.2.2. Thread Pool
    • 5.2.3. Thread Per Session
    • 5.2.4. Thread Per Request
  • 5.3. PolyORB Tasking configuration
  • 5.4. PolyORB ORB Controller policies
    • 5.4.1. No Tasking
    • 5.4.2. Workers
    • 5.4.3. Half Sync/Half Async
    • 5.4.4. Leader/Followers
  • 5.5. PolyORB ORB Controller configuration
• 6. CORBA
  • 6.1. What you should know before Reading this section
  • 6.2. Installing CORBA application personality
  • 6.3. IDL-to-Ada compiler
    • 6.3.1. Usage of iac
    • 6.3.2. Usage of idlac
    • 6.3.3. Difference between idlac and iac
  • 6.4. Resolving names in a CORBA application
    • 6.4.1. po_cos_naming
    • 6.4.2. Registering the reference to the COS Naming server
    • 6.4.3. Using the COS Naming
  • 6.5. The CORBA Interface Repository
    • 6.5.1. po_ir
    • 6.5.2. Using the Interface Repository
  • 6.6. Building a CORBA application with PolyORB
    • 6.6.1. echo example
    • 6.6.2. Other examples
  • 6.7. Configuring a CORBA application
    • 6.7.1. Configuring PolyORB
    • 6.7.2. Configuring GIOP protocol stack for PolyORB
    • 6.7.3. Configuring Security services for PolyORB
    • 6.7.4. Command line arguments
  • 6.8. Implementation Notes
    • 6.8.1. Tasking
    • 6.8.2. Implementation of CORBA specifications
    • 6.8.3. Additions to the CORBA specifications
    • 6.8.4. Interface repository
    • 6.8.5. Policy Domain Managers
    • 6.8.6. Mapping of exceptions
    • 6.8.7. Additional information to CORBA::Unknown
    • 6.8.8. Internals packages
  • 6.9. PolyORB’s specific APIs
    • 6.9.1. PolyORB.CORBA_P.CORBALOC
    • 6.9.2. PolyORB.CORBA_P.Naming_Tools
    • 6.9.3. PolyORB.CORBA_P.Server_Tools
• 7. RT-CORBA
  • 7.1. What you should know before Reading this section
  • 7.2. Installing RT-CORBA
  • 7.3. Configuring RT-CORBA
    • 7.3.1. PolyORB.RTCORBA_P.Setup
  • 7.4. RTCORBA.PriorityMapping
  • 7.5. RTCosScheduling Service
    • 7.5.1. Overview
    • 7.5.2. RTCosScheduling::ClientScheduler
    • 7.5.3. RTCosScheduling::ServerScheduler
• 8. Ada Distributed Systems Annex (DSA)
  • 8.1. Introduction to the Ada DSA
    • 8.1.1. Architecture of a Distributed Ada Application
    • 8.1.2. Categorization Pragmas
    • 8.1.3. Pragma Declared Pure
    • 8.1.4. Pragma Remote_Call_Interface
    • 8.1.5. Pragma Remote_Types
    • 8.1.6. Pragma Shared_Passive
    • 8.1.7. More About Categorization Pragmas
  • 8.2. Partition Communication Subsystem
    • 8.2.1. Marshalling and Unmarshalling Operations
    • 8.2.2. Incorrect Remote Dispatching
    • 8.2.3. Partition Ids
    • 8.2.4. Concurrent Remote Calls
    • 8.2.5. Consistency and Elaboration
    • 8.2.6. Abortion and Termination
  • 8.3. Most Features in One Example
  • 8.4. A small example of a DSA application
  • 8.5. Building a DSA application with PolyORB
    • 8.5.1. Introduction to PolyORB/DSA
    • 8.5.2. How to Configure a Distributed Application
    • 8.5.3. Gnatdist Command Line Options
    • 8.5.4. The Configuration Language
    • 8.5.5. Partition Runtime Parameters
    • 8.5.6. Gnatdist Internals
    • 8.5.7. PolyORB PCS Internals
  • 8.6. Running a DSA application
• 9. MOMA
  • 9.1. What you should know before Reading this section
  • 9.2. Installing MOMA application personality
  • 9.3. Package hierarchy
• 10. GIOP
  • 10.1. Installing GIOP protocol personality
  • 10.2. GIOP Instances
    • 10.2.1. IIOP
    • 10.2.2. SSLIOP
    • 10.2.3. DIOP
    • 10.2.4. MIOP
  • 10.3. Configuring the GIOP personality
    • 10.3.1. Common configuration parameters
    • 10.3.2. IIOP Configuration Parameters
    • 10.3.3. SSLIOP Configuration Parameters
    • 10.3.4. DIOP Configuration Parameters
    • 10.3.5. MIOP Configuration Parameters
  • 10.4. Code sets
    • 10.4.1. Supported code sets
    • 10.4.2. Incompatibility in code set support
    • 10.4.3. Adding support for new code sets
    • 10.4.4. Character data Converter
    • 10.4.5. Converters factories
    • 10.4.6. Registering new code sets
• 11. SOAP
  • 11.1. Installing SOAP protocol personality
  • 11.2. Configuring the SOAP personality
• 12. Tools
  • 12.1. po_catref
  • 12.2. po_dumpir
  • 12.3. po_names
• 13. Performance Considerations
• 14. Conformance to Standards
  • 14.1. CORBA standards conformance
    • 14.1.1. CORBA IDL-to-Ada mapping
    • 14.1.2. CORBA Core
    • 14.1.3. CORBA Interoperability
    • 14.1.4. CORBA Interworking
    • 14.1.5. CORBA Quality Of Service
    • 14.1.6. CORBA COS Services
    • 14.1.7. CORBA Specialized services
  • 14.2. RT-CORBA standards conformance
  • 14.3. CSIv2 standards conformance
  • 14.4. CORBA/GIOP standards conformance
  • 14.5. SOAP standards conformance
• 15. References

About This Guide

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

It describes the features of the middleware and related APIs and tools, and details how to use them to build Ada 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.

• Ada Distributed Systems Annex (DSA) describes PolyORB’s implementation of the Ada Distributed Systems Annex.

• MOMA describes PolyORB’s implementation of MOMA, the Message Oriented Middleware for Ada.

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

• Performance Considerations discusses possible configuration adjustments to optimize PolyORB’s run time performance.

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

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