PolyORB/src/ROADMAP

PolyORB source code roadmap
---------------------------

$Id$

The source code of PolyORB is not for the faint of heart.
Caveat emptor. This document gives a very high-level overview
of how the code is organized.

1. Support components used throughout PolyORB
---------------------------------------------

./polyorb.ads

Empty package, provides a common namespace for generic ORB
components.

./polyorb-log.ads

Logging facility. Provides a unified means for other units
to output debugging, diagnostics and error messages.

./polyorb-configuration.ads

User control of various middleware aspects is implemented
through a generic configuration framework. 

At start-up, PolyORB will search for various configuration files,
containing application profiles. See 'polyorb.conf' for a detail
of PolyORB generic configuration, 'moma/*.conf' for MOMA specific
configuration files.

./polyorb-types.ads

Base data types used throughout PolyORB.

./polyorb-annotations.ads

The Annotation pattern, which allows clients of a data structure
to independently enrich it, thus decoupling data extension from
type extension.

./polyorb-components.ads

The Component pattern, which allows objects to exchange
synchronous messages through connections, thus decoupling
behaviour profiles from Ada typing.

./polyorb-dynamic_dict.ads

Efficient dictionnary of key-value pairs.

./polyorb-initialization.ads

Software modules manager for initialization of the middleware.
Each module is registered with this package, indicating its
dependencies. Initialization is performed as a topological
sort of the dependency lattice. A check is performed to
control consistency of the tree.

./polyorb-utils-chained_lists.ads

Generic chain list facility with generic iterator

./polyorb-utils-dynamic_tables.ads
./polyorb-utils-htables-perfect.ads
./polyorb-utils-htables.ads
./polyorb-utils-semaphores.ads

./polyorb-utils-simple_flags.ads

Utility functions to provide binary flag sets.

./polyorb-utils-strings-lists.ads
./polyorb-utils-strings.ads

Handling of dynamic string allocation and chained lists of
strings.

./polyorb-sequences.ads
./polyorb-sequences-bounded.ads
./polyorb-sequences-unbounded.ads

{Bounded,unbounded} variable length arrays (cf. CORBA.Sequences.)
Notionally based on Ada.Strings.Unbounded.

./polyorb-tasking-*

Tasking runtime, support full tasking, ravenscar tasking subset and no
tasking modes. Provides advanced mutexes, mutexes, watchers, r/w locks
abstractions.

2. Neutral core
---------------

./polyorb-any*.ads

Neutral, self-descriptive data representation.

./polyorb-requests.ads

The central data structure in PolyORB: an object representing a method
invocation request to be executed by an object in a way that is independant
of the application and protocol personalities.

./polyorb-jobs.ads

A Job is anything that can keep a task busy (like a Runnable
in Java). This unit declares an abstract Job type, and a means
to maintain job queues.

./polyorb-asynch_ev.ads

Asynchronous event sources objects, which can trigger asynchronous
ORB activities to react to external stimuli.

./polyorb-orb.ads

The core component: provides the global ORB activites scheduler,
as well as registries for personality components (binding object
factories, transport access points, object adapters).

./polyorb-binding_data.ads

Client-side remote binding object factories.

./polyorb-references.ads

Object reference management

./polyorb-references-binding.ads

Client-side binding factory. Either binds directly
or creates a binding to a remote object.

3. Protocol layer framework and support functionalities
-------------------------------------------------------

./polyorb-opaque-chunk_pools.ads
./polyorb-opaque.ads
./polyorb-buffers.ads

Manage memory buffers for various purposes

./polyorb-utils-buffers.ads
./polyorb-utils-text_buffers.ads

Utilities for buffer access.

./polyorb-filters.ads

Framework for layered components that form a protocol stack.
Each filter transmits SDUs (service data units) from its
lower layer to its upper layer, and can perform some
processing on the SDU and its associated data.

The lowest layer is a polyorb.filters.sockets.socket_filter,
which does not receive SDUs from a lower layer but directly
from the ORB engine.

The uppermost layer is a Session, which does not actually
transmits SDUs to an upper layer but takes action based on
received SDUs.

./polyorb-transport.ads

The abstraction of access points and end points in the transport service.
An access point is an entity that has an address, to which other nodes
can connect. An end point is an entity that represents an established
connection with an access point, and can be used to exchange information.

./polyorb-transport-sockets.ads

A concrete implementation of the classes defined in PolyORB.Transport,
based on TCP sockets.

./polyorb-representations.ads

The abstraction of a method to represent data in a form
suitable for transmission. Children of this unit are expected
to derive the PolyORB.Representations.Representation abstract
type into a concrete type implementing one representation
mechanism.

./polyorb-protocols.ads

The abstraction of a remote invocation protocol. To be derived
by concrete personalities. A Protocol is a factory of Session.
A Session is the actual object that implements one particular
protocols. Protocols are factories of Sessions, and are used
as parts of binding object factories.

4. Protocol personalities
-------------------------

./soap/

Directory containing the SOAP protocol personality.

./corba/polyorb-protocol-giop-*

GIOP protocol personality. GIOP revisions 1.0, 1.1, 1.2 are implemented.

./srp/

The Simple Request Protocol, a simple HTTP-like protocol for rapid
prototyping of PolyORB functionalities. It is incomplete and provided
solely to test simple method invocations. May be useful to invoke 'by
hand' servants and test some particular configurations.

5. Application layer framework and support functionalities
----------------------------------------------------------

./polyorb-call_back.ads

Interceptor for request processing completion signalling.

./polyorb-obj_adapters.ads

The abstract interface of object adapters in PolyORB.

./polyorb-poa.ads

The base class for all Portable Object Adapter implementations (generic
hierarchical object adapters modeled after the CORBA POA.)

./polyorb-poa_types.ads

Base data structures handled by PolyORB.POA.

./polyorb-poa_policies.ads

Children of this unit define various policy objects that can be used
to customise the behaviour of portable object adapters.

./polyorb-servants.ads

Base class for all application objects.

6. Application personalities
----------------------------

* CORBA:

./corba/corba-*.ads

Standard CORBA packages.

./corba/polyorb-corba_p-*.ads

PolyORB-specific components of the CORBA personality. This includes
internal utility components, as well as some tools that can be used
directly by application developers (eg PolyORB.CORBA_P.Server_Tools).

* DSA:

./dsa/s-polint.ads

Wrapper between GNAT generated code and PolyORB internals.

./dsa/polyorb-poa_config-racws.ads

Configuration of the POA for RACW.

* MOMA:

./moma/moma-configuration* 

Utility function to extract configuration information from
configuration files.

./moma/moma-connection_factories*
./moma/moma-connections*
./moma/moma-destinations*

Definition of MOMA Connection_Factory, Connection and Destination types.

./moma/moma-message_consumer*

MOMA client objects and API to receive messages from a pool. It
contains stub routines to interact with a Message_Consumer servant.
It is the façade shown to the client to the message receiving part of
MOMA specification.

./moma/moma-message_producer*

MOMA client objects and API to send messages to a pool. It contains
stub routines to interact with a Message_Producer servant.  It is the
façade shown to the client to the message sending part of MOMA
specification.

./moma/moma-messages*

API to construct the different types of MOMA messages.

./moma/moma-provider.ads

Base package for MOMA provider, collection of servants providing MOM
functionalities on top of PolyORB neutral core layer.

./moma/moma-provider-message_consumer.ads

Servant object implementing Message_Consumer object that interacts
with message pools. This package contains both its skeleton and
implementation subroutines. By construction, its implementation
contains parts of a stub to access the Message_Pool object.

./moma/moma-provider-message_producer.ads

Servant object implementing Message_Producer object that interacts
with message pools. This package contains both its skeleton and
implementation subroutines. By construction, its implementation
contains parts of a stub to access the Message_Pool object.

./moma/moma-provider-message_pool.ads

Servant object implementing Message_Pool object. This package contains
both its skeleton and implementation subroutines.

./moma/moma-provider-warehouse.ads

Implementation of a placeholder for received messages.

./moma/moma-sessions*

Definition of the session type (see JMS definition for more details).

./moma/moma-types.ads

All MOMA types.