1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <!--
   5 
   6 Copyright (c) 2003, Oracle and/or its affiliates. All rights reserved.
   7 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   8 
   9 This code is free software; you can redistribute it and/or modify it
  10 under the terms of the GNU General Public License version 2 only, as
  11 published by the Free Software Foundation.  Oracle designates this
  12 particular file as subject to the "Classpath" exception as provided
  13 by Oracle in the LICENSE file that accompanied this code.
  14 
  15 This code is distributed in the hope that it will be useful, but WITHOUT
  16 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  17 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  18 version 2 for more details (a copy is included in the LICENSE file that
  19 accompanied this code).
  20 
  21 You should have received a copy of the GNU General Public License version
  22 2 along with this work; if not, write to the Free Software Foundation,
  23 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  24 
  25 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  26 or visit www.oracle.com if you need additional information or have any
  27 questions.
  28 -->
  29 </head>
  30 <body bgcolor="white">
  31 
  32 <p>This package is the top-level package for the <b>PEPt Remoting
  33 Architecture</b>.  PEPt enables remoting (i.e., RPC and Messaging)
  34 systems to <em>dynamically use alternate encodings, protocols and
  35 transports</em>.</p>
  36 
  37 <h2>Related Documentation</h2>
  38 
  39 <p>
  40 For 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>
  50 PEPt stands for:
  51 <ul>
  52 
  53 <li><b>Presentation</b>: the data types that may be passed and the
  54 APIs used to interact with the remoting system.</li>
  55 
  56 <li><b>Encoding</b>: the process of transforming those programming
  57 language data types into an underlying "wire" representation (and the
  58 wire representation itself).</li>
  59 
  60 <li><b>Protocol</b>: The metadata which accompanies a message and the
  61 use of that metadata.</li>
  62 
  63 <li><b>transport</b>: The mechanism used to move the encoded data and
  64 metadata 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
 234 message by calling
 235 <code>ClientRequestDispatcher.marshalingComplete</code>.</li>
 236 <li> <code>ClientRequestDispatcher.marshalingComplete</code> sends the
 237 headers 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
 241 immediately (i.e., an asynchronous message send with no
 242 acknowledgment), may wait to get an indication that the message send
 243 was successfully (i.e., an acknowledged asynchronous send) or wait for
 244 a response (a synchronous message send). The following steps assume
 245 waiting for a response.</li>
 246 <li> <code>ClientRequestDispatcher.marshalingComplete</code> waits for a
 247 response.  This may mean blocking on a read of the
 248 <code>Connection</code> (e.g., SOAP/HTTP), or putting the client
 249 thread to sleep while another thread demultiplexes replies (e.g.,
 250 RMI-IIOP), or using the client thread itself to perform the
 251 server-side operation (e.g., colocation optimization).</li>
 252 <li> When a response arrives on the <code>Connection</code> it gives
 253 the raw bits of the response to <code>ContactInfo</code> which creates
 254 an EPT-specific <code>InputObject</code> and calls
 255 <code>ProtocolHandler.handleRequest</code> to determine the message
 256 type.</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
 266 interceptors and use reply header metadata befor returning control to
 267 the presentation block.</li>
 268 <li> The presentation block call to
 269 <code>ClientRequestDispatcher.marshalingComplete</code> would return
 270 the 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
 274 the invocation is complete by calling
 275 <code>ClientRequestDispatcher.endRequest</code>.</li>
 276 <li> <code>ClientRequestDispatcher.endRequest</code> may clean up
 277 resources 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
 287 the <code>Acceptor</code> is responsible for adding its EPT
 288 information (e.g., address information) to the object reference.</li>
 289 <li> The <code>Acceptor</code> acts as a "listener" for client
 290 connection requests.</li>
 291 <li> When the <code>Acceptor</code> receives a connection request it
 292 creates an EPT-specific <code>Connection</code> on which to receive
 293 messages.</li>
 294 <li> When <code>Connection</code> receives a message, it gives the raw
 295 bits of the message to <code>Acceptor</code> which creates an
 296 EPT-specific <code>InputObject</code> and calls
 297 <code>ProtocolHandler.handleRequest</code> to determine the message
 298 type.</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
 341 factories for all other objects involved in a message for a particular
 342 EPT. 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
 354 of resources such as transport managers, thread pools, thread local
 355 data structures, etc.</li>
 356 </ul>
 357 
 358 </body>
 359 </html>