TAO/README.sun

   1 ========================================
   2
   3 This file contains the original README that came with the SunSoft IIOP
   4 release.  This information in this file is historical in nature and
   5 the much of the specific information probably is inaccurate with
   6 respect to the current state of TAO.  Please see the ./README file
   7 that comes with TAO for up-to-date information.
   8
   9 Specifically, some of the files referred to below have been renamed in
  10 TAO.
  11
  12 ========================================
  13
  14 @(#)README      1.2 97/02/03
  15
  16 Inter-ORB Engine
  17 ================
  18
  19 02-Feb, 1997
  20 Version 1.4
  21
  22         -=+=-   -=+=-   -=+=-   -=+=-   -=+=-   -=+=-   -=+=-
  23
  24     As of today, this is the most current version of the "IIOP Engine".
  25     It's doubtful that a later one will be released by Sun Microsystems.
  26
  27     This still supports only IIOP v1.0 (no fragmentation or security
  28     extensions) and contains a few bugs (GIOP service context typecode
  29     is wrong).  This version was completed before the COM/CORBA
  30     "Part A" RFP cycle, as well as the "Secure IOP" work.
  31
  32     It's different from other versions in that it has (a) the benefit
  33     of much performance work, including support for multithreading,
  34     (b) the source code is reorganized to display more of the internal
  35     structure, and (c) it incorporates a simple COM glue layer (which
  36     is not the same as the one later standardized by the OMG).  There
  37     is surely more; for example, experimental XDR marshaling support.
  38
  39     Documentation hasn't particularly been updated.  It'll need more work
  40     to run "out of the box" since it doesn't use autoconf just now.
  41
  42     Please drop me a line (brownell@ix.netcom.com) if you're using this.
  43
  44             - Dave
  45
  46         -=+=-   -=+=-   -=+=-   -=+=-   -=+=-   -=+=-   -=+=-
  47
  48
  49 INTRODUCTION
  50 ------------
  51 Welcome to the Inter-ORB Engine!  This is the source code version of
  52 SunSoft's portable implementation of the CORBA 2.0 mandatory "IIOP"
  53 interoperability protocol for networked ORBs.
  54
  55 This is a preliminary version.  This software is made available AS IS and
  56 WITH NO GUARANTEES.  Please make sure you read and understand the copyright
  57 and license notice under which this software is distributed.  This notice
  58 may be found in the "LICENSE" file that is part of this distribution, and
  59 also in the corba/orb.hh header file used by every source file.  Note that
  60 both commercial and noncommercial usage is allowed.
  61
  62 The rest of this document includes these sections:
  63
  64     - ENGINE OVERVIEW
  65     - TARGET AUDIENCE
  66     - HOW TO OBTAIN THIS SOFTWARE
  67     - CONTACT POINT AND WORKING ALIAS
  68     - ABOUT THIS IIOP SOFTWARE DISTRIBUTION
  69     - WHAT ARE:  IOP, IIOP, GIOP, ESIOP, AND DCE-CIOP?
  70
  71 For instructions on how to build and test this software, see the file
  72 named "BUILDING" in the "docs" directory. [Note, this is renamed to
  73 TAO-Install.html for TAO].
  74
  75 ENGINE OVERVIEW
  76 ---------------
  77 The Inter-ORB Engine implementation is composed of four parts.  Each of
  78 these is found in a top level directory with the name used here:
  79
  80  *  "runtime" ... this defines the public binary interface to the engine, as
  81         used by application (and test) programs.  It has three main parts:
  82
  83         - A CDR (Common Data Representation) marshaling engine, which encodes
  84           simple OMG-IDL data types directly and uses a TypeCode interpreter
  85           to marshal complex ones;
  86
  87         - The TypeCode interpreter is used to manipulate all legal OMG-IDL
  88           data types using just standard OMG-IDL TypeCodes;
  89
  90         - The runtime framework itself includes a partial ORB implementation.
  91           Its programming interfaces are specified in CORBA and it provides
  92           the OMG-IDL C++ mapping of those abstractions in most cases;
  93
  94  *  "bridge" ... this is an IIOP-specific module which talks to the runtime
  95         and to TCP-based sockets to send, receive, and dispatch IIOP messages.
  96
  97  *  "test" ... code for a few basic functional tests is included.
  98
  99  *  "docs" ... text files, such as this one, describe the way the
 100         implementation works.  This is oriented toward people who are
 101         maintaining, porting, or otherwise enhancing this code.
 102
 103 The package is not a full ORB.  It doesn't support the full set of CORBA
 104 APIs, an IDL compiler, an Interface Repository, a standard object adapter,
 105 and more.  You could use this software to help build an ORB, but you
 106 would need to enhance it.
 107
 108 If you have an interest in using an IDL compiler to generate TypeCodes,
 109 stubs, and/or skeletons, you may be interested in the portable front end
 110 for an OMG-IDL compiler which is available through the OMG FTP server.
 111 Further information may be found in this file:
 112
 113     ftp.omg.org:/pub/OMG_IDL/ANNOUNCEMENT
 114
 115
 116 TARGET AUDIENCE
 117 ---------------
 118 Who should use this release?
 119
 120 - Organizations which are providing their own implementations of the IIOP
 121   should use this software to perform protocol testing, helping to ensure
 122   that they can in fact interoperate with each other.
 123
 124 - Bridge builders, including ORB implementors who have their own ORB
 125   protocols, can use this software to bootstrap bridge construction work.
 126   This includes bridge builders working to bridge COM and CORBA.
 127
 128 - ORB implementors can use this to acquire a TypeCode interpreter.  (ORBs
 129   compliant with CORBA 2.0 CORE need one to support the dynamic runtime
 130   typing APIs, such as Any, DII, and DSI.)
 131
 132 - ORB implementors without their own protocols can use this software to add
 133   networked object capabilities to their systems, using the Internet IOP.
 134
 135 - Implementors of systems which are intended to talk with ORBs may wish to
 136   use this software when bridging to ORBs from non-CORBA systems.  A few
 137   examples:  (a) specialized applications that don't need a full ORB as
 138   infrastructure; (b) "legacy" code which needs either to use an ORB or to
 139   be used by one; (c) users or providers other object systems, such as
 140   programming environments, which want ORB connectivity.
 141
 142 - And of course, this is the core of a portable ORB, and may be used as
 143   one by providing the rest of the CORBA 2.0 programming interfaces and
 144   development tools such as one or more IDL compilers.
 145
 146
 147 HOW TO OBTAIN THIS SOFTWARE
 148 ---------------------------
 149 There are several distribution sites for this software, and it may also be
 150 restributed through other ones.  Not all sites will necessarily have the
 151 most recent version.
 152
 153 OMG MAIL SERVER -- You can use a mail server program to retrieve this
 154 software. Send email with a body line 'help' to iiop-bridging@omg.org, and
 155 the mail server will respond with a copy of this README file.  Send email
 156 with a body line "iiop" and it will return a SHAR file of this software.
 157
 158 OMG FTP SERVER -- You may also use anonymous FTP to the "ftp.omg.org" server.
 159 To do this the classic (pre-Web) Internet way, use FTP to sign on with the
 160 username "ftp" and your Internet email address as your password.  Then change
 161 directory to "/pub/interop" and retrieve:
 162
 163     - "iiop.sh.Z" ... compressed SHAR format, for UNIX systems
 164     - "iiop.tar.Z" ... compressed TAR format, also for UNIX systems
 165     - "iiop.zip" ... ZIP format, for MS-Windows systems
 166
 167 In Web-speak, those files are named by these URLs:
 168
 169     ftp://ftp.omg.org/pub/interop/iiop.sh.Z     ... compressed SHAR format
 170     ftp://ftp.omg.org/pub/interop/iiop.tar.Z    ... compressed TAR format
 171     ftp://ftp.omg.org/pub/interop/iiop.zip      ... PC ZIP format
 172
 173 Copies of this software may be made available from archives other than
 174 omg.org. New versions made available by Sun will be placed on omg.org and a
 175 message will be sent to the comp.object newsgroup announcing availability.
 176
 177
 178 CONTACT POINT AND WORKING ALIAS
 179 -------------------------------
 180 Please let us know who you are if you decide to use this software, and how
 181 you use it. Please send e-mail to:
 182
 183      omg-iiop-bridge@sun.com
 184
 185 This address can also be used to report problems, bugs (or better yet, fixes!),
 186 suggestions and send general comments.  It is not a general mailing list for
 187 discussion about IIOP implementations.
 188
 189 There is at least one general access alias intended for discussion about
 190 IIOP implementations.  You can subscribe by sending email with a subject
 191 line of "subscribe" to:
 192
 193     iiop-impl-request@jsoft.com
 194
 195
 196 ABOUT THIS IIOP SOFTWARE DISTRIBUTION
 197 -------------------------------------
 198 On some platforms POSIX threads (P1003.1c; draft 10 became the standard)
 199 will be available to users of this distribution.  There are still legal
 200 client side message sequences which will not be emitted by this distribution
 201 (namely, requests being sent on a connection while a response is pending),
 202 though by definition the server side must (and will!) accept them when they
 203 are produced by other implementations of the IIOP.
 204
 205 Also, note that although this is written in C++, ANSI C++ exceptions are not
 206 required.  This derives from a goal to have this software be highly portable.
 207 (Few C++ compilers fully comply with the C++ exception specifications.)
 208
 209 Developers should not be surprised to find implementation or specification
 210 problems at this point in time.  When they do, they are encouraged to
 211 communicate such problems through the contact point (for problems with this
 212 implementation of IIOP; see above) or the OMG interoperability revision
 213 task force (for specification problems; see the REFERENCES file) so that
 214 they can be resolved.  If you need complete and final ORB software, you
 215 should use a commercially available ORB product.
 216
 217 There are areas where the software is known to be incomplete; for example,
 218 it does not provide Interface Repository APIs.  It is expected that bridge
 219 and ORB implementors will add the missing pieces as appropriate for their
 220 environments.  In some cases these may be added in future distributions
 221 of this software.
 222
 223 See the "DIFFERENCES" file for information about where this software differs
 224 from current OMG specifications.  As a rule, these differences are to
 225 establish compatibility with CORBA 2.0 specifications which are being
 226 prepared but which are not (as of this writing) available.  In some cases,
 227 they address recently recognized problems that are yet to be resolved.
 228
 229 For a brief description of the implementation, including goals, notes, and
 230 an overview of the source file organization, see the "IMPLEMENTATION" file.
 231
 232 For a brief overview of the functional tests, see the "TESTS" file.
 233
 234
 235 WHAT ARE:  IOP, IIOP, GIOP, ESIOP, AND DCE-CIOP?
 236 ------------------------------------------------
 237 Inter-ORB Protocols (IOPs) support communication between or within ORBs.
 238
 239 The "Internet IOP" (IIOP) is the protocol adopted by OMG that is required
 240 to be supported by CORBA 2.0 compliant Networked ORBs, either as a native
 241 protocol or through half bridges.  It is a mapping of the "General IOP"
 242 (GIOP) onto the Internet's TCP transport layer.  Mappings onto other
 243 transport layers may be defined in the future.
 244
 245 ORBs are free to support optional Environment Specific IOPs (ESIOPs) as
 246 their preferred ORB protocols.  The "DCE-Common IOP" (DCE-CIOP) is the the
 247 first such protocol that has been publicly specified.  It uses a subset of
 248 DCE-RPC facilities, and reuses parts of the GIOP.  ORB implementors building
 249 on top of DCE are likely to comply with DCE-CIOP, and bridge to the IIOP
 250 for communication with ORBs not using the DCE-CIOP.
 251
 252 Of course, other ESIOPs exist and will continue to exist, both in ORBs built
 253 on top of other distributed computing environments such as ONC+ and ones
 254 independent of such environments.  Due to the prevalence of such ESIOPs,
 255 most ORBs are expected to interoperate through bridging to the IIOP.
 256