======================================== 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, many of the file referred to in here may not appear 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. 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.