| blob | c07c18a82174efe1d6be7f40576c56988a04a346 |
3 <!-- -->
5 <HTML>
6 <HEAD>
14 </HEAD>
18 <P>
22 <STRONG>
28 </STRONG>
29 </P>
32 Center for Distributed Object Computing<BR>
33 Washington University at St.Louis
34 </P>
36 <HR>
38 <P>
41 To be an effective platform for performance-sensitive real-time and
42 embedded applications, off-the-shelf CORBA middleware must preserve
43 the communication-layer quality of service (QoS) properties of
44 applications end-to-end. However, the standard CORBA GIOP/IIOP
45 interoperability protocols are not well suited for applications that
46 cannot tolerate the message footprint size, latency, and jitter
47 associated with general-purpose messaging and transport protocols.
48 Fortunately, the CORBA specification defines the notion of
49 "Environmentally-Specific Inter-ORB Protocols" (ESIOPs) that can be
50 used to integrate non-GIOP/IIOP protocols beneath an ORB. <P>
52 To allow end-users and developers to take advantage of ESIOP
53 capabilities, it is useful for an ORB to support a <EM>pluggable
54 protocols framework</em> that allows custom messaging and transport
55 protocols to be configured flexibly and used transparently by
56 applications. This document explains how to develop pluggable
57 protocols using TAO's pluggable protocols framework. Here are some
58 links that describe TAO's pluggable protocols framework, though not
59 how to implement one: <BLOCKQUOTE> <A
62 <A HREF="http://www.dre.vanderbilt.edu/~schmidt/PDF/PfHSN.pdf">http://www.dre.vanderbilt.edu/~schmidt/PDF/PfHSN.pdf</A><BR>
63 <A
64 HREF="http://www.dre.vanderbilt.edu/~schmidt/PDF/pluggable_protocols.pdf">http://www.dre.vanderbilt.edu/~schmidt/PDF/pluggable_protocols.pdf</A>
65 </BLOCKQUOTE>
67 <P>
68 <HR>
70 <UL>
71 <LI><A NAME="TOC_SECTION100" HREF="#SECTION100">Overview of Implementation of Pluggable Protocols for TAO</A>
72 <UL>
75 <UL>
77 <LI><A NAME="TOC_SECTION122" HREF="#SECTION122">Basics of Implementing a Pluggable Protocol for TAO</A>
78 </UL>
79 </UL>
81 <UL>
83 <UL>
89 </UL>
91 <UL>
97 </UL>
101 <UL>
107 </UL>
109 <UL>
110 <LI><A NAME="TOC_SECTION261" HREF="#SECTION261"><TT>Connection_Handler</TT> Implementation</A></LI>
111 </UL>
112 </UL>
113 <LI><A NAME="TOC_SECTION300" HREF="#SECTION300">Notes From a ``Real World'' Pluggable Protocol Implementation</A>
115 <UL>
117 </UL>
120 </UL>
121 <!-- End of Table of Contents -->
122 <BR><HR>
125 <P>
128 Overview of Implementation of Pluggable Protocols for TAO</A>
129 </H3>
131 <P>
132 There are several basic implementation details that should be followed when
133 implementing pluggable protocols for
135 section describes them.
137 <P>
140 The Hard Way</A>
141 </H3>
143 <P>
144 It is possible to implement a pluggable protocol for TAO without using
146 components, or using existing pluggable protocols as a reference, but that is
147 certainly more difficult than taking advantage of the code reuse offered by
148 using existing ACE and TAO models and implementations.
150 <P>
153 The Path of Least Resistance</A>
154 </H3>
156 <P>
157 TAO takes advantage of the many useful encapsulations provided by ACE. These
160 use these encapsulations some requirements must be satisfied.
162 <P>
165 Basic Requirements</A>
166 </H3>
168 <P>
169 To be able to successfully use the ACE components listed above, the underlying
170 protocol used in the pluggable protocol for TAO should support the following
171 features and characteristics:
173 <P>
175 <UL>
176 <LI>Access to a session/connection via some type of handle (e.g. a UNIX file descriptor
180 to the open sessions/connections. This ability is required in order to use the
182 implementations.
184 <P>
185 Some underlying transports do not provide any such ability. However, it may
186 sometimes be possible to separate data delivery from notification. For example,
187 TAO's shared memory transport transports data through shared memory, but since
189 must be used for notification. One way to do this is to use a local IPC connection
190 strictly for notification purposes. Whenever, data is sent through shared memory,
191 a byte of data could be written to the local IPC connection. That local IPC
192 connection would be used to notify the receiving process that data is available
195 dispatching for the shared memory pluggable protocol.
197 <P>
198 </LI>
199 <LI>A pluggable protocol should sit on top of lower-level implementation. The underlying
200 protocol implementation should not rely on any resources/features that are at
201 a similar or higher layer of abstraction than the pluggable protocol. For example,
203 to hidden windows or the use of a window message pump then the underlying pluggable
204 protocol may be difficult or pointless to implement as a pluggable protocol.</LI>
205 </UL>
207 <P>
210 Basics of Implementing a Pluggable Protocol for TAO</A>
211 </H3>
213 <P>
214 One of the easiest ways to implement a pluggable protocol for TAO is to do the
215 following:
217 <P>
219 <OL>
230 the necessary TAO pluggable protocol components should be fairly easy. In fact,
231 much of the code can be ``cut and pasted'' from existing TAO pluggable protocol
232 implementations. For example, TAO's UIOP pluggable protocol was, for the most
233 part, based entirely on the IIOP pluggable protocol code found in TAO's ``tao/IIOP_*''
234 source files. The only things that had to be changed for UIOP were the protocol
235 prefix, address format and URL style IOR format. Each of these pluggable protocol
236 characteristics is documented later in this documentation.</LI>
237 </OL>
239 <P>
241 The next section goes into detail about TAO's pluggable protocol
242 framework components and their public interfaces. It is our goal that
243 no changes to ACE or TAO should be necessary to implement a pluggable
244 protocol. Naturally, as with all frameworks, it's only possible to
245 achieve this goal if (1) all possible use-cases are understood in
246 advance or (2) the framework is generalized when confronted with new
247 use-cases that weren't handled before. Therefore, we describe the
248 conditions that must currently hold in order to develop and integrate
249 a pluggable protocol for TAO.
250 <P>
251 <HR>
252 <P>
254 Pluggable Protocol Framework Components</A>
255 </H3>
257 <P>
258 In order for a pluggable protocol to be usable by TAO <STRONG><EM>without</EM></STRONG> making any modifications
259 to TAO itself, it must be implemented to provide the functionality dictated
260 by TAO's pluggable protocols framework interface. This functionality is implemented
265 <P>
269 </H3>
271 <P>
274 <P>
277 Context</A>
278 </H3>
280 <P>
281 A server can accept connections at one or more endpoints, potentially using
282 the same protocol for all endpoints. The set of protocols that an ORB uses to
283 play the client role need not match the set of protocols used for the server
285 that only makes requests, in which case it can use several protocols to make
286 requests, but receive no requests from other clients.
288 <P>
291 Problem</A>
292 </H3>
294 <P>
295 The server must generate an IOR that includes all possible inter-ORB and transport-protocol-specific
296 profiles for which the object can be accessed. As with the client, it should
297 be possible to add new protocols without changing the ORB.
299 <P>
302 Solution</A>
303 </H3>
305 <P>
308 with the Connector pattern, an Acceptor decouples the connection establishment
309 from the processing performed on that connection. However, in the Acceptor pattern,
312 <P>
315 Applying the solution to TAO</A>
316 </H3>
318 <P>
319 Figure <A HREF="#server">1</A> illustrates how TAO's pluggable protocols framework leverages
320 the design presented in Section <A HREF="#design:transparent"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
323 for implementing the External Polymorphism pattern [<A HREF="#Schmidt:97e">2</A>] and encapsulating itself
326 <P>
328 <P></P>
330 <TABLE>
332 Server Pluggable Protocol Class Diagram</CAPTION>
333 <TR><TD><P>
335 <P>
338 <!-- MATH
339 $\resizebox* {5in}{!}{\includegraphics{graphics/server.eps}}$
340 -->
341 <IMG
345 <P>
347 </TABLE>
348 </DIV><P></P>
350 <P>
353 the ACE implementation of the Acceptors. This pattern also permits a seamless
356 Handler</TT>s are responsible for performing I/O with their connected peers. In
358 Handlers</TT> implemented as abstract classes. This design shields the ORB from
360 Handler</TT>s for each particular protocol.
362 <P>
367 object, hiding the transport- and strategy-specific details of the acceptor.
369 <P>
373 </H3>
375 <P>
379 abstract base class.
381 <P>
384 <DT>
386 {<BR>
388 // Abstract Acceptor class used for pluggable protocols.<BR>
391 // Base class for the Acceptor bridge calls.<BR>
392 public:<BR>
394
396 <BR>
400 <BR>
404 <BR>
406
408 <BR>
412 <BR>
414 // The tag, each concrete class will have a specific tag value.
416 <BR>
418
420 <BR>
424 <BR>
428 <BR>
430
432 <BR>
436 <BR>
438 int version_major,
440 <BR>
442 int version_minor,
444 <BR>
446 const char *address,
448 <BR>
450 const char *options = 0) = 0;
452 <BR>
456 <BR>
458
460 <BR>
464 <BR>
466 const char *options = 0) = 0;
468 <BR>
470 // Open an acceptor on the default endpoint for this protocol
472 <BR>
474
476 <BR>
480 <BR>
484 <BR>
486
488 <BR>
490 virtual int create_mprofile (const TAO_ObjectKey &object_key,
492 <BR>
494 TAO_MProfile &mprofile) = 0;
496 <BR>
498 // Create the corresponding profile for this endpoint.
500 <BR>
502
504 <BR>
506 virtual int is_collocated (const TAO_Profile* profile) = 0;
508 <BR>
510 // Return 1 if the <profile> has the same endpoint as the acceptor.
512 <BR>
514
516 <BR>
520 <BR>
522 // Returns the number of endpoints this acceptor is listening on. This
524 <BR>
526 // is used for determining how many profiles will be generated
528 <BR>
532 <BR>
534
536 <BR>
537 protected:
539 <BR>
543 <BR>
547 <BR>
549
551 <BR>
552 private:
554 <BR>
558 <BR>
562 <BR>
564
566 <BR>
568 };
571 </DL>
572 A description of each of the methods that must be implemented follows:
574 <P>
576 <DL>
579 implementation, nothing else is really done in the constructor. For example,
581 <P>
584 <DT>
588 <BR>
592 <BR>
596 <BR>
600 <BR>
604 <BR>
608 <BR>
612 <BR>
614 {
616 <BR>
618 }</DD>
619 </DL>
620 <P>
623 available in the
625 of this document. In this case,
627 for the CORBA IIOP protocol. Until a tag that uniquely
628 identifies the protocol is assigned, a tag value that isn't
629 used by any other protocol can be used in the meantime.
630 </DL>
632 <P>
633 <DL>
636 the protocol version to use (if supported), parses any protocol-specific options
637 (if any) and creates the endpoint passed to it.
638 <P>
639 The address specified by using the <TT><A HREF="../Options.html#-ORBEndpoint">-ORBEndpoint</A></TT> ORB option is passed
640 directly to this method. If more than one address is specified within a given
643 command line option:
645 <P>
648 <DT>
650 </DL>
651 <P>
654 <P>
657 <DT>
660 </DL>
661 <P>
663 by TAO's pluggable protocols framework. It is up to the pluggable protocol to
664 handle the address passed to this method.
666 <P>
667 </DD>
669 <DD>Each pluggable protocol should have the ability to
670 open a default endpoint. For example, it should be possible to make the pluggable
671 protocol open an endpoint without specifying an address, in which case an address
673 options such as the following are used:
675 <P>
678 <DT>
680 </DL>
681 <P>In this case, an IIOP endpoint will be created on the local host. The port will
683 in the following manner:
685 <P>
688 <DT>
690 </DL></DD>
691 <P>
694 down any open endpoints, and recovers resources as necessary. This method is
695 automatically invoked by the pluggable protocols framework when the ORB associated
696 with that endpoint is shut down.</DD>
697 <P>
701 object, basically a container that holds multiple profiles, passed to it. The
702 code for this method is typically ``boilerplate,'' i.e. it can be based almost
704 Here is how it is implemented in TAO's IIOP acceptor:
706 <P>
709 <DT>
711 TAO_IIOP_Acceptor::create_mprofile (const TAO_ObjectKey &object_key, <BR>
713 <BR>
714 {
715 <BR>
717 <BR>
719 <BR>
721 <BR>
722 && mprofile.grow (count + 1) == -1)
723 <BR>
725 <BR>
726
727 <BR>
729 <BR>
731 <BR>
732 TAO_IIOP_Profile (this->host_.c_str (),
733 <BR>
734 this->address_.get_port_number (),
735 <BR>
736 object_key,
737 <BR>
738 this->address_,
739 <BR>
740 this->version_,
741 <BR>
742 this->orb_core_),
743 <BR>
744 -1);
745 <BR>
746
747 <BR>
749 <BR>
751 <BR>
753 <BR>
755 <BR>
757 <BR>
759 <BR>
760
761 <BR>
762 if (this->orb_core_->orb_params ()->std_profile_components () == 0)
763 <BR>
765 <BR>
766
767 <BR>
769 <BR>
770
771 <BR>
773 <BR>
775 <BR>
777 <BR>
779 <BR>
781 <BR>
783 <BR>
784
785 <BR>
786 pfile->tagged_components ().set_tao_priority (this->priority ());
787 <BR>
788
789 <BR>
792 <P>
794 }</DD>
795 </DL>
796 <P>
797 Most of the code that is common to all pluggable protocols will be factored
798 out of this method in the near future.
800 <P>
801 </DD>
805 underlying layer between the operating system calls and a pluggable protocol,
806 this code is also ``boilerplate.'' TAO's IIOP implementation does the following:
808 <P>
811 <DT>
813 <BR>
815 <BR>
816 {
817 <BR>
819 <BR>
821 <BR>
822 pfile);
823 <BR>
824
825 <BR>
826 // compare the port and sin_addr (numeric host address)
827 <BR>
829 <BR>
830 }</DD>
831 </DL></DD>
832 <P>
838 </DL>
840 <P>
844 </H3>
846 <P>
849 <P>
852 Context</A>
853 </H3>
855 <P>
856 When a client references an object, the ORB must obtain the corresponding profile
857 list, which is derived from the IOR and a profile ordering policy, and transparently
858 establish a connection to the server.
860 <P>
863 Problem</A>
864 </H3>
866 <P>
867 There can be one or more combinations of inter-ORB and transport protocols available
868 in an ORB. For a given profile, the ORB must verify the presence of the associated
869 IOP and transport protocol, if available. It must then locate the applicable
872 <P>
875 Solution</A>
876 </H3>
878 <P>
881 to a remote object. This pattern decouples the connection establishment from
882 the processing performed after the connection is successful. As before, the
885 <P></P>
887 <TABLE>
889 Connection Establishment Using Multiple Pluggable Protocols</CAPTION>
890 <TR><TD><P>
892 <P>
894 <P>
897 <!-- MATH
898 $\resizebox* {9cm}{!}{\includegraphics{graphics/pp_e2e.eps}}$
899 -->
900 <IMG
904 <P>
906 </TABLE>
907 </DIV><P></P>
909 profile selected for use will depend on the set of Policies active at the time
910 of connection establishment. However, once a profile is selected, the connector
911 registry matches the profile type, represented by a well known tag, with an
914 <P>
917 Applying the solution in TAO</A>
918 </H3>
920 <P>
923 for the ACE implementation of the Connector pattern. Thus, they are typically
924 lightweight objects that simply delegate to a corresponding ACE component.
926 <P>
929 <P></P>
931 <TABLE>
933 Client Pluggable Protocol Class Diagram</CAPTION>
934 <TR><TD><P>
936 <P>
939 <!-- MATH
940 $\resizebox* {5in}{!}{\includegraphics{graphics/client.eps}}$
941 -->
942 <IMG
946 <P>
948 </TABLE>
949 </DIV><P></P>
954 registries. In both cases, the profile is created with a matching tag. The tag
956 handle each profile.
958 <P>
959 As shown in the same figure, the Connector Registry manipulates only the base
960 classes. Therefore, new protocols can be added without requiring any modification
961 to the existing pluggable protocols framework. When a connection is successfully
965 <P>
969 </H3>
971 <P>
975 abstract base class.
977 <P>
980 <DT>
982 <BR>
983 {
984 <BR>
986 <BR>
988 <BR>
990 <BR>
992 <BR>
993 // Base class for connector bridge object.
994 <BR>
995 public:
996 <BR>
997
998 <BR>
1000 <BR>
1002 <BR>
1003
1004 <BR>
1006 <BR>
1008 <BR>
1009
1010 <BR>
1012 <BR>
1013 // The tag identifying the specific ORB transport layer protocol.
1014 <BR>
1015 // For example TAO_TAG_IIOP_PROFILE = 0. The tag is used in the
1016 <BR>
1017 // IOR to identify the type of profile included. IOR -> {{tag0,
1018 <BR>
1019 // profile0} {tag1, profole1} ...} GIOP.h defines typedef
1020 <BR>
1022 <BR>
1023
1024 <BR>
1026 <BR>
1027 TAO_MProfile &mprofile,
1028 <BR>
1029 CORBA::Environment &ACE_TRY_ENV);
1030 <BR>
1031 // Parse a string containing a URL style IOR and return an
1032 <BR>
1034 <BR>
1035
1036 <BR>
1038 <BR>
1039 // Initialize object and register with reactor.
1040 <BR>
1041
1042 <BR>
1044 <BR>
1045 // Shutdown Connector bridge and concreate Connector.
1046 <BR>
1047
1048 <BR>
1050 <BR>
1051 TAO_Transport *&,
1052 <BR>
1053 ACE_Time_Value *max_wait_time) = 0;
1054 <BR>
1055 // To support pluggable we need to abstract away the connect()
1056 <BR>
1057 // method so it can be called from the GIOP code independent of the
1058 <BR>
1060 <BR>
1061
1062 <BR>
1063 virtual int preconnect (const char *preconnections) = 0;
1064 <BR>
1065 // Initial set of connections to be established.
1066 <BR>
1067
1068 <BR>
1069 virtual TAO_Profile *create_profile (TAO_InputCDR& cdr) = 0;
1070 <BR>
1071 // Create a profile for this protocol and initialize it based on the
1072 <BR>
1074 <BR>
1075
1076 <BR>
1077 virtual int check_prefix (const char *endpoint) = 0;
1078 <BR>
1079 // Check that the prefix of the provided endpoint is valid for use
1080 <BR>
1082 <BR>
1083
1084 <BR>
1085 virtual char object_key_delimiter (void) const = 0;
1086 <BR>
1087 // Return the object key delimiter to use or expect.
1088 <BR>
1089
1090 <BR>
1092 <BR>
1094 <BR>
1096 <BR>
1098 <BR>
1099
1100 <BR>
1101 protected:
1102 <BR>
1104 <BR>
1105 TAO_Profile *&,
1106 <BR>
1107 CORBA::Environment &ACE_TRY_ENV) = 0;
1108 <BR>
1109 // Create a profile with a given endpoint.
1110 <BR>
1111
1112 <BR>
1113 private:
1114 <BR>
1116 <BR>
1118 <BR>
1119 };</DD>
1120 </DL>A description of each of the methods that must be implemented follows:
1122 <P>
1124 <DL>
1127 base class should be initialized with the tag associated with the pluggable
1129 constructor:
1130 <P>
1133 <DT>
1135 <BR>
1137 <BR>
1139 <BR>
1141 <BR>
1142 {
1143 <BR>
1144 }</DD>
1145 </DL></DD>
1146 <P>
1150 example, TAO's IIOP pluggable protocol uses an
1152 <P>
1155 <DT>
1157 <BR>
1158 ACE_SOCK_CONNECTOR></DD>
1159 </DL>as its underlying connection strategy. No connection establishment occurs here.
1163 <P>
1164 </DD>
1168 <P>
1171 to the endpoint encoded within the IOR in use. It should first verify that the
1173 with the pluggable protocol. If the tags do not match then an attempt use a
1176 <P>
1179 Handler</TT> being used.
1181 <P>
1182 </DD>
1184 <DD>The <TT>preconnect</TT> method is invoked when the <TT><A HREF="../Options.html#-ORBPreconnect">-ORBPreconnect</A></TT>
1185 ORB option is used. It causes a blocking connection to be made to the specified
1186 address. Multiple connections can be made to the same endpoint. For example,
1188 to be made to the specified host and port:
1190 <P>
1193 <DT>
1195 </DL>
1196 <P>
1198 will be factored out into a common method. Pluggable protocols will still be
1202 <P>
1203 </DD>
1206 in a URL style IOR or preconnect endpoint is valid for use with a given pluggable
1208 pluggable protocol looks like the following:
1210 <P>
1213 <DT>
1215 <BR>
1217 <BR>
1218 {
1219 <BR>
1221 <BR>
1223 <BR>
1225 <BR>
1226
1227 <BR>
1228 const char *protocol[] = { "iiop", "iioploc" };
1229 <BR>
1230
1231 <BR>
1232 size_t slot = ACE_OS::strchr (endpoint, ':') - endpoint;
1233 <BR>
1234
1235 <BR>
1237 <BR>
1239 <BR>
1240
1241 <BR>
1242 // Check for the proper prefix in the IOR. If the proper prefix
1243 <BR>
1244 // isn't in the IOR then it is not an IOR we can use.
1245 <BR>
1247 <BR>
1248 && ACE_OS::strncasecmp (endpoint, protocol[0], len0) == 0)
1249 <BR>
1251 <BR>
1253 <BR>
1254 && ACE_OS::strncasecmp (endpoint, protocol[1], len1) == 0)
1255 <BR>
1257 <BR>
1258
1259 <BR>
1261 <BR>
1263 <BR>
1265 <BR>
1266 }</DD>
1267 </DL>
1268 <P>
1269 It checks that the protocol prefix in a URL style IOR (e.g. <TT>corbaloc:iiop:foo.bar.com:1234/...</TT>)
1270 or preconnect endpoint matches the one(s) supported by the IIOP pluggable protocol,
1274 in future TAO releases.
1276 <P>
1277 This method is important for TAO's implementation of the CORBA Interoperable
1278 Naming Service.
1280 <P>
1281 </DD>
1283 <DD>The object key delimiter within a URL style
1284 IOR is the character that separates the address from the object key. For example,
1285 in the following IIOP URL style IOR:
1287 <P>
1290 <DT>
1292 </DL>
1293 <P>
1295 for all pluggable protocols, such as TAO's UIOP pluggable protocol, because
1296 addresses within a URL style IOR may contain that very same character. A typical
1297 TAO UIOP URL style IOR may look something like:
1299 <P>
1302 <DT>
1304 </DL>
1305 <P>
1310 For instance, if an IIOP object key delimiter was used in a UIOP URL style IOR
1311 as follows:
1313 <P>
1316 <DT>
1318 </DL>
1319 <P>
1324 <P>
1326 that contains the object key delimiter appropriate for the given pluggable protocol.
1328 <P>
1329 </DD>
1331 <DD>This method creates and initializes a profile using
1332 the provided CDR stream. Most of this code is also ``boilerplate.'' As such,
1333 it may be factored out in future TAO releases.</DD>
1334 <P>
1337 be ``cut and pasted'' from existing TAO pluggable protocols. It is simply
1339 an object reference of the form:
1341 <P>
1344 <DT>
1346 </DL>
1347 <P>
1348 or
1349 <P>
1351 <DT>
1353 </DL>
1354 <P>
1358 <P></DD>
1359 </DL>
1361 <P>
1365 </H3>
1367 <P>
1369 to create and parse a protocol-specific IOR, in addition to representing object
1371 definitions.
1373 <P>
1376 is declared in the file
1378 Its interface follows. Only the methods that must be implemented are shown:
1381 <P>
1384 <DT>
1386 <BR>
1387 {
1388 <BR>
1390 <BR>
1392 <BR>
1394 <BR>
1396 <BR>
1397 // An abstract base class for representing object address or location
1398 <BR>
1399 // information. This is based on the CORBA IOR definitions.
1400 <BR>
1402 <BR>
1403 public:
1404 <BR>
1405
1406 <BR>
1408 <BR>
1409 CORBA::Environment &ACE_TRY_ENV) = 0;
1410 <BR>
1411 // Initialize this object using the given input string.
1412 <BR>
1414 <BR>
1415
1416 <BR>
1417 virtual char* to_string (CORBA::Environment &ACE_TRY_ENV) = 0;
1418 <BR>
1419 // Return a string representation for this profile. client must
1420 <BR>
1422 <BR>
1423
1424 <BR>
1425 virtual int decode (TAO_InputCDR& cdr) = 0;
1426 <BR>
1427 // Initialize this object using the given CDR octet string.
1428 <BR>
1429
1430 <BR>
1431 virtual int encode (TAO_OutputCDR &stream) const = 0;
1432 <BR>
1433 // Encode this profile in a stream, i.e. marshal it.
1434 <BR>
1435
1436 <BR>
1438 <BR>
1439 // Obtain the object key, return 0 if the profile cannot be parsed.
1440 <BR>
1442 <BR>
1443
1444 <BR>
1445 virtual CORBA::Boolean is_equivalent (const TAO_Profile* other_profile) = 0;
1446 <BR>
1447 // Return true if this profile is equivalent to other_profile. Two
1448 <BR>
1449 // profiles are equivalent iff their key, port, host, object_key and
1450 <BR>
1452 <BR>
1453
1454 <BR>
1456 <BR>
1457 CORBA::Environment &ACE_TRY_ENV) = 0;
1458 <BR>
1460 <BR>
1461
1462 <BR>
1463 virtual int addr_to_string (char *buffer, size_t length) = 0;
1464 <BR>
1465 // Return a string representation for the address. Returns
1466 <BR>
1467 // -1 if buffer is too small. The purpose of this method is to
1468 <BR>
1469 // provide a general interface to the underlying address object's
1470 <BR>
1471 // addr_to_string method. This allowsthe protocol implementor to
1472 <BR>
1474 <BR>
1475
1476 <BR>
1478 <BR>
1479 // This method is used with a connection has been reset requiring
1480 <BR>
1481 // the hint to be cleaned up and reset to NULL.
1482 <BR>
1483 };</DD>
1484 </DL>TAO's existing pluggable protocols have a static member containing the object
1485 key delimiter specific to the given pluggable protocol, in addition to a static
1486 protocol prefix accessor method that simply returns a pointer to a static string
1487 containing the protocol prefix specific to the pluggable protocol. Note that
1488 both of these members will always remain constant so there is no problem in
1489 making them static.
1491 <P>
1492 Theses static member are:
1494 <P>
1496 <DL>
1499 delimiter specific to the given pluggable protocol. A typical definition looks
1500 like:
1501 <P>
1504 <DT>
1506 </DL></DD>
1509 that contains the protocol prefix specific to the pluggable protocol in use.
1510 The static string for the IIOP pluggable protocol is:
1512 <P>
1515 <DT>
1517 </DL>
1518 <P>
1521 <P>
1524 <DT>
1526 <BR>
1528 <BR>
1529 {
1530 <BR>
1532 <BR>
1533 }</DD>
1534 </DL></DD>
1535 </DL>
1536 Note that it not strictly necessary to implement equivalent versions of these
1537 static members. TAO's implementation just happens to use them. However, pluggable
1538 protocol implementations that are based on TAO's pluggable protocols may need
1539 them.
1541 <P>
1543 that must be implemented. A description of each of these methods:
1545 <P>
1547 <DL>
1549 <DD>TAO's existing pluggable protocols each implement several
1551 are not strictly required to implement analogs to all of the constructors in
1552 existing TAO pluggable protocols, it is generally a good idea to do so. All
1554 class with the tag associated with the pluggable protocol. The object key should
1556 <P>
1559 object using the provided string. The string passed to this method has the format:
1560 <P>
1563 <DT>
1565 </DL>
1566 <P>
1567 or
1569 <P>
1572 <DT>
1574 </DL>
1577 the protocol version (even if it isn't used), the address and the object key
1579 methods in TAO's existing pluggable protocols as a reference when implementing
1580 this method.
1582 <P>
1583 </DD>
1585 <DD>This method returns the URL style representation of the
1587 is also ``boilerplate.'' However, the address part of the URL style IOR, returned
1588 by this method should be specific to the pluggable protocol. For example, the
1589 address in the following IIOP URL style IOR:
1591 <P>
1594 <DT>
1596 </DL>
1598 protocols may also be factored out because that code is common to all pluggable
1599 protocols. The URL style IOR created by this method should be usable
1603 <P>
1604 </DD>
1606 <DD>The input CDR stream reference passed to this method is used
1608 object reference information found within the CDR stream. Care must be taken
1609 to extract the information in the correct order. Use existing TAO pluggable
1612 <P>
1614 method.
1616 <P>
1617 </DD>
1621 Care must be taken to insert the information in the correct order. Use existing
1624 <P>
1626 method.
1628 <P>
1629 </DD>
1637 <P>
1640 <DT>
1642 <BR>
1644 <BR>
1645 {
1646 <BR>
1648 <BR>
1649
1650 <BR>
1652 <BR>
1653 TAO_ObjectKey (this->object_key_),
1654 <BR>
1655 0);
1656 <BR>
1657
1658 <BR>
1660 <BR>
1661 }</DD>
1662 </DL></DD>
1663 <P>
1666 CORBA specified method of the same name. It should return true if this profile
1667 is equivalent to the profile to which it is being compared. Two profiles are
1669 are the same.</DD>
1670 <P>
1676 the largest value the hash can be.
1678 <P>
1679 Any algorithm deemed suitable to provide the required functionality may be used.
1681 hash algorithms.
1683 <P>
1684 </DD>
1688 The stringified address should have the same form that the address in the URL
1689 style IOR has. This method should be reentrant.</DD>
1690 <P>
1695 method may be implemented as a ``no-op.'' A pluggable protcol that does not
1698 </DL>
1700 <P>
1704 </H3>
1706 <P>
1711 the given pluggable protocol. TAO iterates through the list of loaded <TT>Protocol
1712 Factories</TT> and invokes a factory operation that creates the desired object:
1715 <P>
1716 All <TT>Protocol_Factory</TT> implementations should be derived from the <TT>TAO_Protocol_Factory</TT>
1717 abstract base class defined in
1721 <P>
1724 <DT>
1725 <DD>class TAO_Export TAO_Protocol_Factory : public ACE_Service_Object
1726 <BR>
1727 {
1728 <BR>
1729 public:
1730 <BR>
1732 <BR>
1734 <BR>
1735
1736 <BR>
1738 <BR>
1740 <BR>
1741
1742 <BR>
1743 virtual int match_prefix (const ACE_CString &prefix);
1744 <BR>
1746 <BR>
1747
1748 <BR>
1750 <BR>
1751 // Returns the prefix used by the protocol.
1752 <BR>
1753
1754 <BR>
1756 <BR>
1757 // Return the character used to mark where an endpoint ends and
1758 <BR>
1760 <BR>
1761
1762 <BR>
1764 <BR>
1766 <BR>
1768 <BR>
1769
1770 <BR>
1772 <BR>
1774 <BR>
1775
1776 <BR>
1777 virtual int requires_explicit_endpoint (void) const = 0;
1778 <BR>
1779 // Some protocols should not create a default endpoint unless the
1780 <BR>
1781 // user specifies a -ORBEndpoint option. For example, local IPC
1782 <BR>
1783 // (aka UNIX domain sockets) is unable to remove the rendesvouz
1784 <BR>
1785 // point if the server crashes. For those protocols is better to
1786 <BR>
1787 // create the endpoint only if the user requests one.
1788 <BR>
1789 };</DD>
1790 </DL>Each of the important methods to be implemented are described below:
1792 <P>
1794 <DL>
1801 The only difference lies in the fact that the option parsing should begin at
1805 allows protocol-specific options to be implemented. Once passed to this method,
1806 the pluggable protocol can use them to, for example, enable or disable certain
1808 components can then use these flags or features as necessary.
1809 <P>
1813 <P>
1816 <DT>
1817 <DD>dynamic IIOP_Factory Service_Object * TAO:_make_TAO_IIOP_Protocol_Factory() "-Foo Bar"</DD>
1818 </DL>
1819 <P>
1824 <P>
1825 </DD>
1827 <DD>This method verifies that protocol prefix contained
1828 in the string passed to matches the one used by the pluggable protocol. A typical
1829 implementation, such as the one used by the IIOP pluggable protocol, looks like:
1831 <P>
1834 <DT>
1836 <BR>
1837
1838 <BR>
1839 int
1840 <BR>
1842 <BR>
1843 {
1844 <BR>
1845 // Check for the proper prefix for this protocol.
1846 <BR>
1847 return (ACE_OS::strcasecmp (prefix.c_str (), ::prefix_) == 0);
1848 <BR>
1849 }</DD>
1850 </DL></DD>
1851 <P>
1854 static string containing the protocol prefix used by the pluggable protocol.</DD>
1855 <P>
1859 However, it used to delimit where an endpoint ends and where its options begin.
1861 priority:
1863 <P>
1866 <DT>
1868 </DL>
1869 <P>
1872 character to be used. For example, TAO's UIOP pluggable protocol implementation
1873 defines the following:
1875 <P>
1878 <DT>
1880 <BR>
1882 <BR>
1883 {
1884 <BR>
1886 <BR>
1887 }</DD>
1888 </DL>
1889 <P>
1890 An endpoint option for the UIOP pluggable protocol can look like the following:
1892 <P>
1895 <DT>
1897 </DL>
1898 <P>
1900 point ends and where the endpoint-specific options begin.
1902 <P>
1905 to the client-side.
1907 <P>
1908 </DD>
1913 TAO's UIOP pluggable protocol implementation defines this method as follows:
1915 <P>
1918 <DT>
1920 <BR>
1922 <BR>
1923 {
1924 <BR>
1926 <BR>
1927
1928 <BR>
1930 <BR>
1931 TAO_UIOP_Acceptor,
1932 <BR>
1933 0);
1934 <BR>
1935
1936 <BR>
1938 <BR>
1939 }</DD>
1940 </DL></DD>
1941 <P>
1946 belongs. TAO's UIOP pluggable protocol implementation defines this method as
1947 follows:
1949 <P>
1952 <DT>
1954 <BR>
1956 <BR>
1957 {
1958 <BR>
1960 <BR>
1961
1962 <BR>
1964 <BR>
1965 TAO_UIOP_Connector,
1966 <BR>
1967 0);
1968 <BR>
1969
1970 <BR>
1972 <BR>
1973 }</DD>
1974 </DL></DD>
1975 <P>
1977 <DD>Some protocols should not create a default
1979 IPC (aka UNIX domain sockets) is unable to remove the rendesvouz point if the
1980 server crashes. For those protocols, it is better to create the endpoint only
1981 if the user requests one. This method is queried by TAO before creating a default
1983 endpoint should be created.</DD>
1984 </DL>
1986 in a certain way. ACE's Service Configurator implementation provides two macros
1987 to ensure that the required additional declarations are made to make an object
1990 is demonstrated by TAO's UIOP pluggable protocol implementation:
1992 <P>
1995 <DT>
1997 <BR>
2000 above two declaration macros. An example of how to use them follows:
2002 <P>
2005 <DT>
2007 <BR>
2008 ASYS_TEXT ("UIOP_Factory"),
2009 <BR>
2010 ACE_SVC_OBJ_T,
2011 <BR>
2012 &ACE_SVC_NAME (TAO_UIOP_Protocol_Factory),
2013 <BR>
2014 ACE_Service_Type::DELETE_THIS |
2015 <BR>
2016 ACE_Service_Type::DELETE_OBJ,
2017 <BR>
2018 0)
2019 <BR>
2020
2021 <BR>
2024 configuration file entries:
2026 <P>
2029 <DT>
2030 <DD>dynamic UIOP_Factory Service_Object * TAO:_make_TAO_UIOP_Protocol_Factory() ""
2031 <BR>
2033 </DL>
2034 <P>
2038 </H3>
2040 <P>
2043 Context</A>
2044 </H3>
2046 <P>
2047 It is desirable to provide for alternative mappings between different ORB messaging
2048 protocols and ORB transport adaptors. For example, a single ORB messaging protocol
2049 such as GIOP can be mapped to any reliable, connection-oriented transport protocol,
2050 such as TCP or TP4. Alternatively, a single transport protocol can be the basis
2052 versions of GIOP differing in the number and types of messages, as well as in
2053 the format of those messages.
2055 <P>
2056 An ORB messaging protocol imposes requirements on any underlying network transport
2057 protocols. For instance, the transport requirements assumed by GIOP, see Section <A HREF="#IOP"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]"
2059 require the underlying network transport protocol to support a reliable, connection-oriented
2060 byte-stream. These requirements are fulfilled by TCP thus leading to the direct
2061 mapping of GIOP onto this transport protocol. However, alternative network transport
2062 protocols such as ATM with AAL5 encapsulation may be more appropriate in some
2063 environments. In this case, the messaging implementation will have to provide
2064 the missing semantics, such as reliability, in order to use GIOP.
2066 <P>
2069 Problem</A>
2070 </H3>
2072 <P>
2073 The ORB Messaging protocol implementations must be independent of the adaptation
2074 layer needed for transports that do not satisfy all their requirements. Otherwise,
2075 the same messaging protocol may be re-implemented needlessly for each transport,
2076 which is time-consuming, error-prone, and time/space inefficient. Likewise,
2077 for those transports that can support multiple ORB Messaging protocols, it must
2078 be possible to isolate them from the details of the ORB messaging implementation.
2079 Care must be taken, however, because not all ORB Messaging protocols can be
2084 <P></P>
2086 <TABLE>
2088 Client Inter-ORB and Transport Class Diagram</CAPTION>
2089 <TR><TD><P>
2091 <P>
2094 <!-- MATH
2095 $\resizebox* {5in}{!}{\includegraphics{graphics/pp_iopc.eps}}$
2096 -->
2097 <IMG
2101 <P>
2103 </TABLE>
2104 </DIV><P></P>
2106 <P>
2109 Solution</A>
2110 </H3>
2112 <P>
2115 the system into groups of components, each one at a different level of abstraction.<A NAME="tex2html5"
2116 HREF="#foot549"><SUP>1</SUP></A> For the client, the ORB uses a particular ORB messaging protocol to send a
2117 request. This ORB messaging protocol delegates part of the work to the transport
2118 adapter component that completes the message and sends it to the server. If
2120 satisfy the requirements of the ORB messaging protocol, the ORB transport adapter
2121 component can implement them.
2123 <P>
2124 In the server, the transport adapter component receives data from the underlying
2125 communication infrastructure, such as sockets or shared memory, and it passes
2126 the message up to the ORB messaging layer. As with the client, this layer can
2127 be very lightweight if the requirements imposed by the ORB messaging layer are
2128 satisfied by the underlying network transport protocol. Otherwise, it must implement
2129 those missing requirements by building them into the concrete transport adapter
2130 component.
2132 <P></P>
2134 <TABLE>
2136 Server Inter-ORB and Transport Class Diagram</CAPTION>
2137 <TR><TD><P>
2139 <P>
2142 <!-- MATH
2143 $\resizebox* {5in}{!}{\includegraphics{graphics/pp_iops.eps}}$
2144 -->
2145 <IMG
2149 <P>
2151 </TABLE>
2152 </DIV><P></P>
2154 <P>
2157 Applying the solution in TAO</A>
2158 </H3>
2160 <P>
2162 implements the messaging protocol and the transport protocol in
2163 separate components. The client ORB uses the current profile to
2164 find the right transport and ORB messaging implementations. The
2165 creation and initialization of these classes is controlled by
2168 messaging/transport tuple.
2171 <P>
2173 server's implementation uses the same transport classes, but
2174 with a different relationship. In particular, the transport
2175 class calls back the messaging class when data is received from
2176 the IPC mechanism. As with the client, a factory, in this case
2178 initializes these objects.
2180 <P>
2184 </H3>
2186 <P>
2195 This somewhat strange design is easy to understand once it is realized
2199 class.
2201 <P>
2203 <TT>TAO_Transport</TT> abstract base class defined in <TT><<A HREF="../../tao/Transport.h">tao/Transport.h</A>></TT>.
2205 that should be implemented for a given pluggable protocol are shown:
2207 <P>
2210 <DT>
2212 <BR>
2213 {
2214 <BR>
2216 <BR>
2217 // Generic definitions for the Transport class.
2218 <BR>
2220 <BR>
2222 <BR>
2223 // The transport object is created in the Service handler
2224 <BR>
2225 // constructor and deleted in the service handler's destructor!!
2226 <BR>
2227
2228 <BR>
2229 public:
2230 <BR>
2232 <BR>
2233 TAO_ORB_Core *orb_core);
2234 <BR>
2235 // default creator, requres the tag value be supplied.
2236 <BR>
2237
2238 <BR>
2240 <BR>
2242 <BR>
2243
2244 <BR>
2246 <BR>
2247 // Call the corresponding connection handler's <close>
2248 <BR>
2250 <BR>
2251
2252 <BR>
2254 <BR>
2256 <BR>
2257
2258 <BR>
2260 <BR>
2261 // This method provides a way to gain access to the underlying file
2262 <BR>
2264 <BR>
2265
2266 <BR>
2267 virtual ACE_Event_Handler *event_handler (void) = 0;
2268 <BR>
2269 // This method provides a way to gain access to the underlying event
2270 <BR>
2272 <BR>
2273
2274 <BR>
2276 <BR>
2277 const ACE_Message_Block *mblk,
2278 <BR>
2279 const ACE_Time_Value *s = 0) = 0;
2280 <BR>
2281 virtual ssize_t send (const ACE_Message_Block *mblk,
2282 <BR>
2283 const ACE_Time_Value *s = 0) = 0;
2284 <BR>
2285 // Write the complete Message_Block chain to the connection.
2286 <BR>
2287 // @@ The ACE_Time_Value *s is just a place holder for now. It is
2288 <BR>
2289 // not clear this this is the best place to specify this. The actual
2290 <BR>
2291 // timeout values will be kept in the Policies.
2292 <BR>
2293
2294 <BR>
2296 <BR>
2297 size_t len,
2298 <BR>
2299 const ACE_Time_Value *s = 0) = 0;
2300 <BR>
2301 // Write the contents of the buffer of length len to the connection.
2302 <BR>
2303
2304 <BR>
2306 <BR>
2307 size_t len,
2308 <BR>
2309 const ACE_Time_Value *s = 0) = 0;
2310 <BR>
2312 <BR>
2313 // @@ The ACE_Time_Value *s is just a place holder for now. It is
2314 <BR>
2315 // not clear this this is the best place to specify this. The actual
2316 <BR>
2317 // timeout values will be kept in the Policies.
2318 <BR>
2319
2320 <BR>
2322 <BR>
2323 const TAO_Profile *profile,
2324 <BR>
2325 TAO_OutputCDR &output,
2326 <BR>
2327 CORBA::Environment &ACE_TRY_ENV =
2328 <BR>
2329 TAO_default_environment ())
2330 <BR>
2332 <BR>
2333 // Fill into <output> the right headers to make a request.
2334 <BR>
2335
2336 <BR>
2338 <BR>
2339 const TAO_Profile *profile,
2340 <BR>
2341 CORBA::ULong request_id,
2342 <BR>
2343 TAO_OutputCDR &output,
2344 <BR>
2345 CORBA::Environment &ACE_TRY_ENV =
2346 <BR>
2347 TAO_default_environment ())
2348 <BR>
2350 <BR>
2351 // Fill into <output> the right headers to make a locate request.
2352 <BR>
2353
2354 <BR>
2356 <BR>
2357 TAO_ORB_Core *orb_core,
2358 <BR>
2359 TAO_OutputCDR &stream,
2360 <BR>
2361 int twoway,
2362 <BR>
2363 ACE_Time_Value *max_time_wait) = 0;
2364 <BR>
2365 // Depending on the concurrency strategy used by the transport it
2366 <BR>
2367 // may be required to setup state to receive a reply before the
2368 <BR>
2370 <BR>
2371 // Using this method, instead of send(), allows the transport (and
2372 <BR>
2374 <BR>
2375
2376 <BR>
2377 virtual int handle_client_input (int block = 0,
2378 <BR>
2379 ACE_Time_Value *max_wait_time = 0);
2380 <BR>
2381 // Read and handle the reply. Returns 0 when there is Short Read on
2382 <BR>
2383 // the connection. Returns 1 when the full reply is read and
2384 <BR>
2386 <BR>
2387 // If <block> is 1, then reply is read in a blocking manner.
2388 <BR>
2389
2390 <BR>
2392 <BR>
2393 // Register the handler with the reactor. Will be called by the Wait
2394 <BR>
2395 // Strategy if Reactor is used for that strategy. Default
2396 <BR>
2397 // implementation out here returns -1 setting <errno> to ENOTSUP.
2398 <BR>
2399
2400 <BR>
2401 };</DD>
2402 </DL>Each method is described below:
2404 <P>
2406 <DL>
2408 <DD>As with all of the TAO pluggable protocol framework components
2411 to the pluggable protocol.</DD>
2412 <P>
2415 method is invoked my this method.</DD>
2416 <P>
2419 <P>
2421 <DD>This method returns the underlying file handle used by the
2423 <P>
2427 <P>
2430 in the underlying transport, such as a TCP connection in the IIOP pluggable
2431 protocol. Three versions of this method must be implemented. Two of them write
2433 sends the data within a buffer of a given length.
2434 <P>
2435 When implementing this method, it is important to be aware of the correct underlying
2438 no further processing of the data being sent is necessary. However, other protocols
2439 may process perform additional operations on the data being sent, in which case
2442 </DD>
2443 <P>
2449 <P>
2451 <DD>This method creates the appropriate header to make
2452 a request and write it into the provided output CDR stream. This method is closely
2454 essentially be the same in all pluggable protocol implementations. The only
2456 this method is only useful for clients.</DD>
2457 <P>
2459 <DD>This method creates the appropriate header to make
2462 implementations should essentially be the same in all pluggable protocol implementations.
2464 Note that this method is only useful for clients. Note that this method is only
2465 useful for clients.</DD>
2466 <P>
2468 <DD>Depending on the concurrency strategy used by the transport
2469 it may be required to setup state to receive a reply before the request is sent.
2471 strategy) to take appropriate action. This method is closely tied to TAO's GIOP
2473 the same in all pluggable protocol implementations. The only thing that should
2475 only useful for clients.</DD>
2476 <P>
2482 clients.</DD>
2483 <P>
2488 be ``boilerplate'' code. It shouldn't differ much between pluggable protocol
2489 implementations if the same ACE event handling and dispatching components are
2490 used. Note that this method may be deprecated in the future.</DD>
2491 </DL>
2493 the default implementations should be more than satisfactory for most pluggable
2494 protocols.
2496 <P>
2497 TAO's existing pluggable protocols implement client-side and server-side specific
2499 pluggable protocols.
2503 </H3>
2508 factories use as their target. Service handlers perform
2509 application-specific processing and communicate via the connection
2513 subclass.
2515 <P>
2519 </H3>
2524 HREF="../../../ace/Svc_Handler.h"><TT>ace/Svc_Handler.h</TT></A>>. TAO's existing pluggable transport protocol
2525 implementations define three classes, a base class derived from an
2527 and a server-side class derived from that base class. Generally, it
2529 on TAO's existing ones. The interfaces for the existing
2532 and
2535 <P>
2536 <HR>
2537 <P>
2540 Notes From a ``Real World'' Pluggable Protocol Implementation</A>
2541 </H3>
2546 <P>This section is based on notes I took when adding a different
2547 transport layer to the TAO ORB. I was given some initial guidelines
2548 on adding an additional protocol and these proved very helpful.
2549 Beyond that there was not much more documentation and so I hope the
2550 information in this paper will serve to further assist anybody whose
2551 is adding a pluggable protocol to the TAO ORB.
2553 <P>I found that in order to successfully add the new protocol capabilities, one had to
2554 have a very good understanding of some of the patterns upon which the ACE framework
2555 is built. These are the REACTOR, ACCEPTOR, CONNECTOR, FACTORY, STRATEGY,
2556 and SERVICE CONFIGURATOR PATTERN. The papers that I found helpful on these
2557 were:
2558 <BR>
2559 <BLOCKQUOTE>
2560 Reactor (
2563 )<BR>
2565 Reactor1-93 (
2568 )<BR>
2570 Reactor2-93 (
2573 )<BR>
2575 reactor-rules (
2578 )<BR>
2580 reactor-siemens (
2583 )<BR>
2585 Svc-Conf (
2586 <A
2589 )<BR>
2591 Acc-Con (
2594 )
2595 </BLOCKQUOTE>
2596 <P>These are all readily available from the TAO and ACE website.
2597 <P>My starting point for understanding how to add a pluggable protocol
2598 to the TAO ORB came from mailing list entry from <A
2600 in the archives of the comp.soft-sys.ace newsgroup. It is dated
2602 the section of that email that was particularly useful to me. (In the
2603 email, he is responding to someone who had inquired about adding the
2604 ATM protocol). <p>
2606 <BLOCKQUOTE>
2607 Basically, you need to look at the following files:<BR>
2609 <BLOCKQUOTE>
2610 IIOP_Profile.{h,i,cpp}<BR>
2611 IIOP_Connector.{h,i,cpp}<BR>
2612 IIOP_Acceptor.{h,i,cpp}<BR>
2613 IIOP_Factory.{h,i,cpp}<BR>
2614 IIOP_Transport.{h,i,cpp}<BR>
2615 Connect.{h,i,cpp} [probably will be renamed IIOP_Connect VSN]
2616 </BLOCKQUOTE>
2618 <P>
2619 The profile class handles the addressing format for your transport.
2620 It would basically be a wrapper around the ACE_ATM_Addr() class. The
2621 Connector and Acceptor classes are simply wrappers around
2624 The factory is even simpler.
2626 <P>
2627 Things get really interesting in the Transport and Connect classes.
2628 Transport just implements external polymorphism over the
2629 Client_Connection_Handler and the Service_Connection_Handler objects
2630 defined in the Connect.{h,i,cpp}, those are simply
2632 they just delegate on the Transport classes. This somewhat strange
2633 design is easy to understand once you realize that all the
2634 ACE_Svc_Handler<> classes are not type compatible (except in
2635 their most basic ACE_Event_Handler form). So they must be wrapped
2636 using the TAO_Transport class.
2637 </BLOCKQUOTE>
2640 <P>Make sure to review
2642 in
2644 ORB (TAO)</A>''
2645 in the
2647 <BR><P>
2648 Just for completeness sake, I'll include some other mailing list entries which were helpful
2649 in getting me started. The following is from <A HREF="mailto:ossama@uci.edu">Ossama Othman</A>.
2651 <BLOCKQUOTE>The stock TAO distribution has support for two transport protocols,
2652 TCP/IP and local namespace sockets (aka Unix Domain sockets). However,
2653 TAO's pluggable protocols framework allows users to add support for
2654 additional transport protocols. All you'd really have to do is
2655 implement a SCRAMNet pluggable transport protocol with the interface
2656 TAO's pluggable protocol framework provides and you'd be able to use
2657 SCRAMNet with TAO just as easily as the IIOP (GIOP over TCP/IP) and
2658 UIOP (GIOP over Unix domains sockets) protocols.
2659 <P>
2660 The idea is to implement GIOP messaging over a SCRAMNet transport. If
2661 you model your implementation on TAO's IIOP and UIOP implementations
2662 then it should be fairly straightforward to create a SCRAMNet
2663 pluggable protocol for TAO. The hard part is implementing the
2664 equivalent ACE classes for SCRAMNet.
2665 <P>
2666 . . .
2667 <P>
2668 It's actually not that bad. The easiest way to add a pluggable protocol
2669 to TAO, IMO, is to base your pluggable protocol on existing ones. As
2670 long as you have the same interface for your protocol as the existing
2671 ones then it is fairly easy to create your TAO pluggable protocol.
2672 However, in order to do that you have to create ACE_SCRAMNet_{Acceptor,
2673 Connector, Stream, Addr} implementations, for example, since TAO's
2674 existing pluggable protocols use those interfaces.
2676 <P>
2677 As long as you use the same interface for your protocol as the
2678 interface for ace/ACE_SOCK* and tao/IIOP* then you shouldn't have much
2679 of a problem.
2680 </BLOCKQUOTE>
2682 <P>
2683 This also assumes that you're implementation can satisfy the
2684 conditions stated earlier in this document.
2686 <P>Note also that the TAO files pluggable.*
2687 are important to review and understand as they contain the abstract
2688 classes that form the common inteface for TAO's pluggable protocol
2689 framework. <BR> <P>Getting a full understanding on how IIOP was
2690 implemented (GIOP over TCP/IP) and also seeing how provisions were
2691 made to add UIOP, was very helpful to adding my own protocol. In
2692 understanding IIOP, I needed to review the section of the OMG CORBA
2693 spec on GIOP, IIOP and Object references and see how this would apply
2694 to my protocol. <BR>
2696 <P>In my case, I added a transport layer that uses SCRAMNet (from
2697 Systran Corp) replicated shared memory hardware. This is actual
2698 physical memory cards located on two different machines. When a
2699 change is made to one memory then that change appears very quickly
2700 (very low latency here) in the other memory. I decided that I would
2701 implement GIOP over SCRAMNet as this seemed to be the simplest. With
2702 SCRAMNet, one could implement this transport layer for the TAO ORB in
2703 a few different ways, GIOP over SCRAMNet, Environment-specific
2704 inter-ORB protocol (ESIOP) or using collocation (since it is shared
2705 replicated memory). I have not done the latter two, only GIOP over
2706 SCRAMNet just to get a proof of concept working.
2708 <BR><P> For a graphical representation of the extensions for the new
2709 SCRAMNet classes I have may a skeletal Rose diagram showing (at this
2710 point) the inheritance relationships of the new and existing classes.
2711 See (TBD) ftp site for this Rose diagram.
2713 <BR><P>
2714 The new classes created were.
2715 <BR>
2716 <BLOCKQUOTE>
2717 TAO_SCRAMNet_Profile (Derived from TAO_Profile in <A HREF="../../tao/Profile.h">Profile.h</A>)<BR>
2718 TAO_SCRAMNet_Acceptor (Derived from TAO_Acceptor in <A HREF="../../tao/Pluggable.h">Pluggable.h</A>) <BR>
2719 TAO_SCRAMNet_Connector (Derived from TAO_Connector in <A HREF="../../tao/Pluggable.h">Pluggable.h</A>)<BR>
2720 TAO_SCRAMNet_Transport (Derived from TAO_Transport in <A HREF="../../tao/Pluggable.h">Pluggable.h</A>)
2722 TAO_SCRAMNet_Client_Transport</BLOCKQUOTE>
2723 TAO_SCRAMNet_Protocol_Factory (Derived from TAO_Protocol Factory in <A HREF="../../tao/Protocol_Factory.h">Protocol_Factory.h</A>)<BR>
2726 TAO_SCRAMNet_Server_Connection_Handler</BLOCKQUOTE></BLOCKQUOTE>
2728 ACE_SCRAMNet_Acceptor<BR>
2729 ACE_SCRAMNet_Connector<BR>
2730 ACE_SCRAMNet_Stream</BLOCKQUOTE>
2731 <P>I closely followed the way that IIOP and UIOP were defined and implemented in the definition and
2732 implementation of the SCRAMNet classes. Following the existing protocol implementation was
2733 the largest source of help for me. Being able to step through the operation of the ORB for
2734 the IIOP protocol and then transposing that over to my protocol made the process relatively painless
2735 and quite the learning experience.
2736 <BR><P>
2738 I am using TAO under Phar Lap's Embedded Tool Suite Real-Time
2739 Operating System which is an RTOS which supports a subset of the Win32
2740 API and Winsock 1.1. Because of the new SCRAMNet transport hardware I
2741 needed to change the ORBs core reactor to a WFMO_Reactor. Any
2742 instance of the TAO ORB can only have one reactor type or it won't
2743 work. In my case I am using an ORB in one thread that uses the
2744 WFMO_Reactor and the SCRAMNet transport, and an ORB in another thread
2745 that uses a Select Reactor and the IIOP protocol. I won't go into
2746 much of the SCRAMNet specific stuff as I assume most people are
2747 interested in adding a pluggable protocol in general. <BR><P>
2749 <P>
2751 RE: IORs<BR>
2752 I found that I needed to have a full understanding of what the exact contents of
2753 a TAO-created IOR were as I needed to be able to understand how to decode the
2754 location information that was now written in the IOR with the SCRAMNet
2755 specific information. Decoding of the preconnect and endpoint info is important.
2756 The endpoint info both in the command line arguments and in the IOR are different
2757 for the each protocol and so your implemention of the new classes has to parse this
2758 information correctly.
2759 <BR><P>
2760 In order to create the ORB with the Win32 Reactor at the core as well as the
2761 SCRAMNet protocol factory loaded and initialize I needed to use the
2762 svc.conf file with the the following options
2765 <BR><P>
2767 </OL>
2769 Beyond the above, I just traced through the operation of the IIOP
2770 protocol in action to see exactly where I needed to just graft on the
2771 new ACE_SCRAMNet classes, the TAO_SCRAMNet classes and their
2772 associated implementations for send and recv so that the SCRAMNet
2773 hardware was used as the transport and not the ethernet hardware.
2774 Questions, comments, changes are welcome. I can be reached at <A
2777 <P>
2778 <HR>
2779 <P>
2781 <H3>
2783 Additional Implementation Information
2784 </A>
2785 </H3>
2787 <P>
2788 This section covers additional information not necessarily related to
2789 TAO's pluggable protocol framework but may still be of interest to
2790 pluggable protocol and ORB developers, nevertheless.
2792 <H3>
2794 Tags
2795 </A>
2796 </H3>
2798 Tags are used to uniquely identify certain parts of an ORB, including
2799 the following:
2800 <P>
2801 <UL>
2807 </UL>
2808 <P>
2810 is available at:
2811 <BLOCKQUOTE>
2812 <A HREF="ftp://ftp.omg.org/pub/docs/ptc/99-05-02.txt">ftp://ftp.omg.org/pub/docs/ptc/99-05-02.txt</A>
2813 </BLOCKQUOTE>
2814 <P>
2815 For information about tags and tag allocation see:
2816 <BLOCKQUOTE>
2817 <A HREF="http://www.omg.org/cgi-bin/doc?ptc/99-02-01">http://www.omg.org/cgi-bin/doc?ptc/99-02-01</A>
2818 </BLOCKQUOTE>
2820 <P>
2821 Information about tags used in TAO is available
2824 <P>
2825 <HR>
2826 <P>
2829 Using a Pluggable Protocol</A>
2830 </H3>
2832 <P>
2833 Once a TAO pluggable protocol is implemented, the ORB is told to load it by
2836 as the following:
2838 <P>
2841 <DT>
2842 <DD>
2843 dynamic FOOIOP_Factory Service_Object * TAO_FOO:_make_TAO_FOOIOP_Protocol_Factory() ""
2844 <BR>
2846 <P>
2847 </DD>
2848 </DL>These entries would cause a pluggable protocol called ``FOOIOP'' to be loaded
2849 into the ORB. By default the IIOP and UIOP (if supported) pluggable protocols
2850 are loaded into TAO if no such entries are provided. Explicitly specifying which
2851 protocols to load in this way prevents any pluggable protocols from being loaded
2852 by default. The
2854 ORB option causes the specified protocol factory to be loaded into the
2855 ORB.
2857 Multiple pluggable protocols can be loaded simply by adding more
2859 entries would cause the TAO's IIOP and the fictional FOOIOP pluggable protocols
2860 to be loaded:
2862 <P>
2865 <DT>
2866 <DD>dynamic FOOIOP_Factory Service_Object * TAO_FOO:_make_TAO_FOOIOP_Protocol_Factory() ""
2867 <BR>
2869 <BR>
2870 dynamic IIOP_Factory Service_Object * TAO:_make_TAO_IIOP_Protocol_Factory() ""
2871 <BR>
2873 <P>
2874 </DD>
2880 ORB option.
2883 <P>
2884 Note that the FOOIOP protocol resides in a library other than the TAO
2887 dynamically load pluggable protocols in libraries that are completely
2888 separate libraries from the TAO library truly makes TAO's pluggable
2889 protocol framework ``pluggable.'' Make sure the directory your
2890 pluggable protocol library is located in is also in your library
2895 <P>
2896 Creating an endpoint specific to a given pluggable protocol is simply a matter
2897 of using TAO's <TT><A HREF="../Options.html#-ORBEndpoint">-ORBEndpoint</A></TT> ORB option. This is detailed in the documentation
2898 for the
2900 and
2902 methods in the
2904 section of this document. Once an endpoint is created, the client uses
2905 the IOR that points to the object on that endpoint to make requests on
2906 that object.
2908 <P>
2911 <P>
2912 <HR>
2913 <P>
2916 Bibliography</A>
2918 <DD>
2919 D. C. Schmidt,
2921 Acceptor and Connector: Design Patterns for Initializing
2922 Communication Services</A>,''
2924 (R. Martin, F. Buschmann, and D. Riehle, eds.), Reading, MA: Addison-Wesley,
2925 1997.
2928 <DD>
2929 C. Cleeland, D. C. Schmidt and T. Harrison,
2931 External Polymorphism -- An Object Structural Pattern for
2932 Transparently Extending Concrete Data Types</A>,''
2934 (R. Martin, F. Buschmann, and D. Riehle, eds.), Reading, MA: Addison-Wesley,
2935 1997.
2938 <DD>
2939 D. C. Schmidt and T. Suda,
2941 An Object-Oriented Framework for Dynamically
2943 Distributed Systems Engineering Journal (Special Issue on Configurable
2947 <DD>
2948 H. Hueni, R. Johnson, and R. Engel, ``A Framework for Network Protocol
2950 October 1995.
2953 <DD>
2954 F. Buschmann, R. Meunier, H. Rohnert, P. Sommerlad, and M. Stal, <A
2959 <DD>
2960 Carlos O'Ryan, Fred Kuhns, Douglas C. Schmidt, Ossama Othman, and Jeff
2961 Parsons, <A
2963 Design and Performance of a Pluggable Protocols Framework for
2964 Real-time Distributed Object Computing Middleware</A>, Proceedings of
2965 the IFIP/ACM <A
2970 Douglas C. Schmidt, Ossama Othman, and Jeff Parsons, <A
2972 Performance of a Pluggable Protocols Framework for Object Request
2978 </DL>
2980 <P>
2983 <DL>
2986 <DD>Protocol stacks based on the Internet or ISO OSI reference models are common
2987 examples of the Layers architecture.
2990 </DL><HR>
2992 <!-- Created: Tue Dec 14 16:53:58 CST 1999 -->
2993 <!-- hhmts start -->
2995 <!-- hhmts end -->
2996 </BODY>
2997 </HTML>