Fix ace_for_tao.mpc

[ACE_TAO.git] / TAO / README.sun

========================================

This file contains the original README that came with the SunSoft IIOP
release.  This information in this file is historical in nature and
the much of the specific information probably is inaccurate with
respect to the current state of TAO.  Please see the ./README file
that comes with TAO for up-to-date information.

Specifically, some of the files referred to below have been renamed in
TAO.

========================================

@(#)README      1.2 97/02/03

Inter-ORB Engine
================

02-Feb, 1997
Version 1.4

        -=+=-   -=+=-   -=+=-   -=+=-   -=+=-   -=+=-   -=+=-

    As of today, this is the most current version of the "IIOP Engine".
    It's doubtful that a later one will be released by Sun Microsystems.

    This still supports only IIOP v1.0 (no fragmentation or security
    extensions) and contains a few bugs (GIOP service context typecode
    is wrong).  This version was completed before the COM/CORBA
    "Part A" RFP cycle, as well as the "Secure IOP" work.

    It's different from other versions in that it has (a) the benefit
    of much performance work, including support for multithreading,
    (b) the source code is reorganized to display more of the internal
    structure, and (c) it incorporates a simple COM glue layer (which
    is not the same as the one later standardized by the OMG).  There
    is surely more; for example, experimental XDR marshaling support.

    Documentation hasn't particularly been updated.  It'll need more work
    to run "out of the box" since it doesn't use autoconf just now.

    Please drop me a line (brownell@ix.netcom.com) if you're using this.

            - Dave

        -=+=-   -=+=-   -=+=-   -=+=-   -=+=-   -=+=-   -=+=-


INTRODUCTION
------------
Welcome to the Inter-ORB Engine!  This is the source code version of
SunSoft's portable implementation of the CORBA 2.0 mandatory "IIOP"
interoperability protocol for networked ORBs.

This is a preliminary version.  This software is made available AS IS and
WITH NO GUARANTEES.  Please make sure you read and understand the copyright
and license notice under which this software is distributed.  This notice
may be found in the "LICENSE" file that is part of this distribution, and
also in the corba/orb.hh header file used by every source file.  Note that
both commercial and noncommercial usage is allowed.

The rest of this document includes these sections:

    - ENGINE OVERVIEW
    - TARGET AUDIENCE
    - HOW TO OBTAIN THIS SOFTWARE
    - CONTACT POINT AND WORKING ALIAS
    - ABOUT THIS IIOP SOFTWARE DISTRIBUTION
    - WHAT ARE:  IOP, IIOP, GIOP, ESIOP, AND DCE-CIOP?

For instructions on how to build and test this software, see the file
named "BUILDING" in the "docs" directory. [Note, this is renamed to
TAO-Install.html for TAO].

ENGINE OVERVIEW
---------------
The Inter-ORB Engine implementation is composed of four parts.  Each of
these is found in a top level directory with the name used here:

 *  "runtime" ... this defines the public binary interface to the engine, as
        used by application (and test) programs.  It has three main parts:

        - A CDR (Common Data Representation) marshaling engine, which encodes
          simple OMG-IDL data types directly and uses a TypeCode interpreter
          to marshal complex ones;

        - The TypeCode interpreter is used to manipulate all legal OMG-IDL
          data types using just standard OMG-IDL TypeCodes;

        - The runtime framework itself includes a partial ORB implementation.
          Its programming interfaces are specified in CORBA and it provides
          the OMG-IDL C++ mapping of those abstractions in most cases;

 *  "bridge" ... this is an IIOP-specific module which talks to the runtime
        and to TCP-based sockets to send, receive, and dispatch IIOP messages.

 *  "test" ... code for a few basic functional tests is included.

 *  "docs" ... text files, such as this one, describe the way the
        implementation works.  This is oriented toward people who are
        maintaining, porting, or otherwise enhancing this code.

The package is not a full ORB.  It doesn't support the full set of CORBA
APIs, an IDL compiler, an Interface Repository, a standard object adapter,
and more.  You could use this software to help build an ORB, but you
would need to enhance it.

If you have an interest in using an IDL compiler to generate TypeCodes,
stubs, and/or skeletons, you may be interested in the portable front end
for an OMG-IDL compiler which is available through the OMG FTP server.
Further information may be found in this file:

    ftp.omg.org:/pub/OMG_IDL/ANNOUNCEMENT


TARGET AUDIENCE
---------------
Who should use this release?

- Organizations which are providing their own implementations of the IIOP
  should use this software to perform protocol testing, helping to ensure
  that they can in fact interoperate with each other.

- Bridge builders, including ORB implementors who have their own ORB
  protocols, can use this software to bootstrap bridge construction work.
  This includes bridge builders working to bridge COM and CORBA.
  
- ORB implementors can use this to acquire a TypeCode interpreter.  (ORBs
  compliant with CORBA 2.0 CORE need one to support the dynamic runtime
  typing APIs, such as Any, DII, and DSI.)

- ORB implementors without their own protocols can use this software to add
  networked object capabilities to their systems, using the Internet IOP.

- Implementors of systems which are intended to talk with ORBs may wish to
  use this software when bridging to ORBs from non-CORBA systems.  A few
  examples:  (a) specialized applications that don't need a full ORB as
  infrastructure; (b) "legacy" code which needs either to use an ORB or to
  be used by one; (c) users or providers other object systems, such as
  programming environments, which want ORB connectivity.

- And of course, this is the core of a portable ORB, and may be used as
  one by providing the rest of the CORBA 2.0 programming interfaces and
  development tools such as one or more IDL compilers.


HOW TO OBTAIN THIS SOFTWARE
---------------------------
There are several distribution sites for this software, and it may also be
restributed through other ones.  Not all sites will necessarily have the
most recent version.

OMG MAIL SERVER -- You can use a mail server program to retrieve this
software. Send email with a body line 'help' to iiop-bridging@omg.org, and
the mail server will respond with a copy of this README file.  Send email
with a body line "iiop" and it will return a SHAR file of this software.

OMG FTP SERVER -- You may also use anonymous FTP to the "ftp.omg.org" server.
To do this the classic (pre-Web) Internet way, use FTP to sign on with the
username "ftp" and your Internet email address as your password.  Then change
directory to "/pub/interop" and retrieve:

    - "iiop.sh.Z" ... compressed SHAR format, for UNIX systems
    - "iiop.tar.Z" ... compressed TAR format, also for UNIX systems
    - "iiop.zip" ... ZIP format, for MS-Windows systems

In Web-speak, those files are named by these URLs:

    ftp://ftp.omg.org/pub/interop/iiop.sh.Z     ... compressed SHAR format
    ftp://ftp.omg.org/pub/interop/iiop.tar.Z    ... compressed TAR format
    ftp://ftp.omg.org/pub/interop/iiop.zip      ... PC ZIP format

Copies of this software may be made available from archives other than
omg.org. New versions made available by Sun will be placed on omg.org and a
message will be sent to the comp.object newsgroup announcing availability.


CONTACT POINT AND WORKING ALIAS
-------------------------------
Please let us know who you are if you decide to use this software, and how
you use it. Please send e-mail to:

     omg-iiop-bridge@sun.com

This address can also be used to report problems, bugs (or better yet, fixes!),
suggestions and send general comments.  It is not a general mailing list for
discussion about IIOP implementations. 

There is at least one general access alias intended for discussion about
IIOP implementations.  You can subscribe by sending email with a subject
line of "subscribe" to:

    iiop-impl-request@jsoft.com


ABOUT THIS IIOP SOFTWARE DISTRIBUTION
-------------------------------------
On some platforms POSIX threads (P1003.1c; draft 10 became the standard)
will be available to users of this distribution.  There are still legal
client side message sequences which will not be emitted by this distribution
(namely, requests being sent on a connection while a response is pending),
though by definition the server side must (and will!) accept them when they
are produced by other implementations of the IIOP.

Also, note that although this is written in C++, ANSI C++ exceptions are not
required.  This derives from a goal to have this software be highly portable.
(Few C++ compilers fully comply with the C++ exception specifications.)

Developers should not be surprised to find implementation or specification
problems at this point in time.  When they do, they are encouraged to
communicate such problems through the contact point (for problems with this
implementation of IIOP; see above) or the OMG interoperability revision
task force (for specification problems; see the REFERENCES file) so that
they can be resolved.  If you need complete and final ORB software, you
should use a commercially available ORB product.

There are areas where the software is known to be incomplete; for example,
it does not provide Interface Repository APIs.  It is expected that bridge
and ORB implementors will add the missing pieces as appropriate for their
environments.  In some cases these may be added in future distributions
of this software.

See the "DIFFERENCES" file for information about where this software differs
from current OMG specifications.  As a rule, these differences are to
establish compatibility with CORBA 2.0 specifications which are being
prepared but which are not (as of this writing) available.  In some cases,
they address recently recognized problems that are yet to be resolved.

For a brief description of the implementation, including goals, notes, and
an overview of the source file organization, see the "IMPLEMENTATION" file.

For a brief overview of the functional tests, see the "TESTS" file.


WHAT ARE:  IOP, IIOP, GIOP, ESIOP, AND DCE-CIOP?
------------------------------------------------
Inter-ORB Protocols (IOPs) support communication between or within ORBs.

The "Internet IOP" (IIOP) is the protocol adopted by OMG that is required
to be supported by CORBA 2.0 compliant Networked ORBs, either as a native
protocol or through half bridges.  It is a mapping of the "General IOP"
(GIOP) onto the Internet's TCP transport layer.  Mappings onto other
transport layers may be defined in the future.

ORBs are free to support optional Environment Specific IOPs (ESIOPs) as
their preferred ORB protocols.  The "DCE-Common IOP" (DCE-CIOP) is the the
first such protocol that has been publicly specified.  It uses a subset of
DCE-RPC facilities, and reuses parts of the GIOP.  ORB implementors building
on top of DCE are likely to comply with DCE-CIOP, and bridge to the IIOP
for communication with ORBs not using the DCE-CIOP.

Of course, other ESIOPs exist and will continue to exist, both in ORBs built
on top of other distributed computing environments such as ONC+ and ones
independent of such environments.  Due to the prevalence of such ESIOPs,
most ORBs are expected to interoperate through bridging to the IIOP.