package.html revision 608:7e06bf1dcb09
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2<html> 3<head> 4<!-- 5 6Copyright (c) 2003, Oracle and/or its affiliates. All rights reserved. 7DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 8 9This code is free software; you can redistribute it and/or modify it 10under the terms of the GNU General Public License version 2 only, as 11published by the Free Software Foundation. Oracle designates this 12particular file as subject to the "Classpath" exception as provided 13by Oracle in the LICENSE file that accompanied this code. 14 15This code is distributed in the hope that it will be useful, but WITHOUT 16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 17FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 18version 2 for more details (a copy is included in the LICENSE file that 19accompanied this code). 20 21You should have received a copy of the GNU General Public License version 222 along with this work; if not, write to the Free Software Foundation, 23Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 24 25Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 26or visit www.oracle.com if you need additional information or have any 27questions. 28--> 29</head> 30<body bgcolor="white"> 31 32<p>This package is the top-level package for the <b>PEPt Remoting 33Architecture</b>. PEPt enables remoting (i.e., RPC and Messaging) 34systems to <em>dynamically use alternate encodings, protocols and 35transports</em>.</p> 36 37<h2>Related Documentation</h2> 38 39<p> 40For papers, slides and examples of the PEPt architecture, please see: 41<ul> 42 <li><a href="http://javaweb.sfbay/~hcarr/rpcMsgFramework/index.html"> 43 Harold Carr's Sun internal PEPt web page</a></li> 44</ul> 45</p> 46 47<h2>PEPt Architecture</h2> 48 49<p> 50PEPt stands for: 51<ul> 52 53<li><b>Presentation</b>: the data types that may be passed and the 54APIs used to interact with the remoting system.</li> 55 56<li><b>Encoding</b>: the process of transforming those programming 57language data types into an underlying "wire" representation (and the 58wire representation itself).</li> 59 60<li><b>Protocol</b>: The metadata which accompanies a message and the 61use of that metadata.</li> 62 63<li><b>transport</b>: The mechanism used to move the encoded data and 64metadata from one location to another.</li> 65 66</ul> 67</p> 68 69<h3>Key PEPt Interfaces</h3> 70<ul> 71 72<li>{@link com.sun.corba.se.pept.transport.ContactInfoList ContactInfoList} 73 - Client-side address selection mechanism and factory for 74 alternate encodings, protocols and transports (EPT).</li> 75 76<li>{@link com.sun.corba.se.pept.transport.Acceptor Acceptor} 77 - Server-side endpoint, addressing and factory for alternate EPTs.</li> 78 79</ul> 80</p> 81 82<h3>PEPt Client-side Interfaces</h3> 83<ul> 84<li><b>Protocol</b> 85 <ul> 86 87 <li>{@link com.sun.corba.se.pept.protocol.ClientDelegate ClientDelegate} 88 - The presentation block interacts with <code>ClientDelegate</code> 89 to initiate and complete a message send (and a possible 90 response). <code>ClientDelegate</code> is a "portability" interface, 91 to allow different vendors to plug in their implementation into a 92 standard presentation block.</li> 93 94 <li>{@link com.sun.corba.se.pept.protocol.ClientRequestDispatcher 95 ClientRequestDispatcher} - This interface controls the client-side 96 dispatch for a given EPT.</li> 97 98 </ul> 99</li> 100<li><b>Transport</b> 101 <ul> 102 103 <li>{@link com.sun.corba.se.pept.protocol.ContactInfoList 104 ContactInfoList} - A list of <code>ContactInfo</code> associated 105 with a <em>ClientDelegate</em></li>. 106 107 <li>{@link com.sun.corba.se.pept.protocol.ContactInfoListIterator 108 ContactInfoListIterator} - An iterator which chooses the "next" 109 EPT-specific <code>ContactInfo</code>.</li> 110 111 <li>{@link com.sun.corba.se.pept.protocol.ContactInfoList 112 ContactInfo} - <em><b>The key PEPt client-side interface.</b></em> The 113 presentation block uses a <code>ClientDelegate</code> to select an 114 EPT-specific <code>ContactInfo</em>. That <code>ContactInfo</em> 115 serves as a factory for EPT-specifc 116 <code>ClientRequestDispatcher</code>, 117 <code>Input/OutputObjects</code> and <code>Connection</code>.</li> 118 119 </ul> 120</li> 121</ul> 122</p> 123 124<h3>PEPt Server-side Interfaces</h3> 125<ul> 126<li><b>Protocol</b> 127 <ul> 128 129 <li>{@link com.sun.corba.se.pept.protocol.ServerRequestDispatcher 130 ServerRequestDispatcher} - This interface controls the server-side 131 dispatch for a given EPT.</li> 132 133 </ul> 134</li> 135<li><b>Transport</b> 136 <ul> 137 138 <li>{@link com.sun.corba.se.pept.protocol.Acceptor Acceptor} 139 - <em><b>The key PEPt server-side interface.</b></em> <code>Aceptor</code> 140 serves as a factory for EPT-specifc 141 <code>ServerRequestDispatcher</code>, 142 <code>Input/OutputObjects</code> and <code>Connection</code>.</li> 143 144 </ul> 145</li> 146</ul> 147</p> 148 149<h3>PEPt Client and Server Interfaces</h3> 150<ul> 151<li><b>Presentation</b> 152 <ul> 153 154 <li>PEPt, at this time, does not provide interfaces for the 155 presentation level. PEPt is the architecture underlying Sun's CORBA 156 implementation. In that implementation the CORBA system provides 157 stubs, ties, DII and DSI presentation artifacts that interact with 158 the underlying PEPt interfaces.</li> 159 160 </ul> 161</li> 162<li><b>Encoding</b> 163 <ul> 164 165 <li>{@link com.sun.corba.se.pept.encoding.InputObject InputObject} 166 - The presentation block uses an <code>InputObject</code> to 167 retrieve programming language typed data from encoded data sent in a 168 message.</li> 169 170 <li>{@link com.sun.corba.se.pept.encoding.OutputObject OutputObject} 171 - The presentation block uses an <code>OutputObject</code> to 172 post programming language typed data to be encoded and sent in a 173 message.</li> 174 175 </ul> 176</li> 177<li><b>Protocol</b> 178 <ul> 179 180 <li>{@link com.sun.corba.se.pept.protocol.MessageMediator MessageMediator} 181 - A "repository" of data associated with a message to be sent or one 182 received. It is the main object used as an argument for methods of 183 the interfaces of the PEPt architecture.</li> 184 185 <li>{@link com.sun.corba.se.pept.protocol.ProtocolHandler ProtocolHandler} 186 - Used to determine an incoming message and dispatch it 187 appropriately.</li> 188 189 </ul> 190</li> 191<li><b>transport</b> 192 <ul> 193 194 <li>{@link com.sun.corba.se.pept.protocol.Connection Connection} 195 - The top-level abstraction of a "connection" between two PEPt 196 peers. Concreate instances may be TCP/IP sockets, Solaris Doors, 197 Shared Memory, ATM, etc.</li> 198 199 </ul> 200</li> 201</ul> 202</p> 203 204<h2>High-level view of PEPt Operation</h2> 205 206<h3>PEPt Client-side Operation</h3> 207 208<ol> 209<li> Presentation asks <code>ClientDelegate</code> for an 210<code>OutputObject</code>.</li> 211 <ol> 212 <li> <code>ClientDelegate</code> gets an EPT-specific 213 <code>ContactInfo</code>.</li> 214 <li> <code>ClientDelegate</code> uses the chosen 215 <code>ContactInfo</code> as a factory to get an EPT-specific 216 <code>ClientRequestDispatcher</code>.</li> 217 <li> <code>ClientDelegate</code> transfers control to the 218 EPT-specific <code>ClientRequestDispatcher.beginRequest</code>. 219 <ol> 220 <li> <code>ClientRequestDispatcher.beginRequest</code> uses 221 <code>ContactInfo</code> as a factory to get EPT-specific 222 <code>OutputObject</code>, <code>MessageMediator</code> and 223 <code>Connection</code>.</li> 224 <li> <code>ClientRequestDispatcher.beginRequest</code> may marshal 225 or set header information on the <code>OutputObject</code> and it 226 may execute interceptors (which may add additional header 227 information) before returning the <code>OutputObject</code> to the 228 presentation block. </li> 229 </ol> 230 </ol> 231<li> Presentation block sets data objects to be sent by calling 232<code>OutputObject</em> methods.</li> 233<li> Presentation block signals the PEPt architecture to send the 234message by calling 235<code>ClientRequestDispatcher.marshalingComplete</code>.</li> 236<li> <code>ClientRequestDispatcher.marshalingComplete</code> sends the 237headers and data encoded in <code>OutputObject</code> on the 238<code>Connection</code>. </li> 239<li> Depending on the EPT, 240<code>ClientRequestDispatcher.marshalingComplete</code> may return 241immediately (i.e., an asynchronous message send with no 242acknowledgment), may wait to get an indication that the message send 243was successfully (i.e., an acknowledged asynchronous send) or wait for 244a response (a synchronous message send). The following steps assume 245waiting for a response.</li> 246<li> <code>ClientRequestDispatcher.marshalingComplete</code> waits for a 247response. This may mean blocking on a read of the 248<code>Connection</code> (e.g., SOAP/HTTP), or putting the client 249thread to sleep while another thread demultiplexes replies (e.g., 250RMI-IIOP), or using the client thread itself to perform the 251server-side operation (e.g., colocation optimization).</li> 252<li> When a response arrives on the <code>Connection</code> it gives 253the raw bits of the response to <code>ContactInfo</code> which creates 254an EPT-specific <code>InputObject</code> and calls 255<code>ProtocolHandler.handleRequest</code> to determine the message 256type.</li> 257 <ol> 258 <li> <code>ProtocolHandler.handleRequest</code> determines the 259 message type (e.g., Request, Response, Error, Cancel, Close, ...).</li> 260 <li> Suppose it is a response to an RMI-IIOP request. In that case 261 it would find the thread and <code>MessageMediator</code> which 262 originated the request and wake it up, after having passed it the 263 response <code>InputObject</code>.</li> 264 </ol> 265<li> <code>ClientRequestDispatcher.marshalingComplete</code> may run 266interceptors and use reply header metadata befor returning control to 267the presentation block.</li> 268<li> The presentation block call to 269<code>ClientRequestDispatcher.marshalingComplete</code> would return 270the response <code>InputObject</code>.</li> 271<li> The presentation block would get response data objects from the 272<code>InputObject</code>.</li> 273<li> The presentation block would signal the PEPt architecture that 274the invocation is complete by calling 275<code>ClientRequestDispatcher.endRequest</code>.</li> 276<li> <code>ClientRequestDispatcher.endRequest</code> may clean up 277resources used in the invocation.</li> 278</ol> 279 280<h3>PEPt Server-side Operation</h3> 281 282<p> Suppose a server support several EPTs.</p> 283 284<ol> 285<li> For each EPT, register an <code>Acceptor</code>.</li> 286<li> If the system supports the concept of an "object reference" then 287the <code>Acceptor</code> is responsible for adding its EPT 288information (e.g., address information) to the object reference.</li> 289<li> The <code>Acceptor</code> acts as a "listener" for client 290connection requests.</li> 291<li> When the <code>Acceptor</code> receives a connection request it 292creates an EPT-specific <code>Connection</code> on which to receive 293messages.</li> 294<li> When <code>Connection</code> receives a message, it gives the raw 295bits of the message to <code>Acceptor</code> which creates an 296EPT-specific <code>InputObject</code> and calls 297<code>ProtocolHandler.handleRequest</code> to determine the message 298type.</li> 299 <ol> 300 <li> <code>ProtocolHandler.handleRequest</code> determines the 301 message type.</li> 302 <li> Suppose it is a request. In that case it would read enough 303 header information to give to <code>Acceptor</code> to get an 304 EPT-specific <code>InputObject</code>, 305 <code>ServerRequestDispatcher</code> and <code>MessageMediator</code>.</li> 306 <li> Control would then transfer to 307 <code>ServerRequestDispatcher.dispatch</code>.</li> 308 <ol> 309 <li> <code>ServerRequestDispatcher.dispatch</code> uses header 310 information to obtain appropriate presentation block artifacts 311 (e.g., Ties, DSI handlers).</li> 312 <li> As an example, a Tie would be given the <code>InputObject</code>.</li> 313 <ol> 314 <li> The Tie would get the request data from the 315 <code>InputObject</code> and make it available to user 316 code.</li> 317 <li> In the case of a synchronous message, the Tie would ask the 318 <code>ServerRequestDispatcher</code> for an 319 <code>OutputObject</code>.</li> 320 <ol> 321 <li> The <code>ServerRequestDispatcher</code> would use the 322 <code>Acceptor</code> as a factory to create the EPT-specific 323 <code>OutputObject</code>.</li> 324 </ol> 325 <li> The Tie would set the response data (normal or error) on 326 the <code>OutputObject</code>. </li> 327 </ol> 328 <li> <code>ServerRequestDispatcher.dispatch</code> would send the 329 header and response data encoded in <code>OutputObject</code> on 330 the <code>Connection</code>.</li> 331 </ol> 332 <li> <code>ServerRequestDispatcher.dispatch</code> may clean up 333 any resources used in the invocation.</li> 334 </ol> 335 </ol> 336</ol> 337 338<h2>Initial ContactInfo and Acceptor Creation</h2> 339 340<p> <code>ContactInfo</code> and <code>Acceptor</code> are the 341factories for all other objects involved in a message for a particular 342EPT. The question naturally arises, how are these created?</p> 343 344<ul> 345<li> From a tool reading service descriptions (e.g., WSDL). </li> 346<li> By reading the contents of an object reference (e.g., CORBA IOR). </li> 347<li> From a configuration file. </li> 348</ul> 349 350<h2>Other PEPt Interfaces</h2> 351 352<ul> 353<li>{@link com.sun.corba.se.pept.broker.Broker Broker} - A repository 354of resources such as transport managers, thread pools, thread local 355data structures, etc.</li> 356</ul> 357 358</body> 359</html> 360