se/pept/package.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--

Copyright (c) 2003, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation.  Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.

This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).

You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
</head>
<body bgcolor="white">

<p>This package is the top-level package for the <b>PEPt Remoting
Architecture</b>.  PEPt enables remoting (i.e., RPC and Messaging)
systems to <em>dynamically use alternate encodings, protocols and
transports</em>.</p>

<h2>Related Documentation</h2>

<p>
For papers, slides and examples of the PEPt architecture, please see:
<ul>
  <li><a href="http://javaweb.sfbay/~hcarr/rpcMsgFramework/index.html">
         Harold Carr's Sun internal PEPt web page</a></li>
</ul>
</p>

<h2>PEPt Architecture</h2>

<p>
PEPt stands for:
<ul>

<li><b>Presentation</b>: the data types that may be passed and the
APIs used to interact with the remoting system.</li>

<li><b>Encoding</b>: the process of transforming those programming
language data types into an underlying "wire" representation (and the
wire representation itself).</li>

<li><b>Protocol</b>: The metadata which accompanies a message and the
use of that metadata.</li>

<li><b>transport</b>: The mechanism used to move the encoded data and
metadata from one location to another.</li>

</ul>
</p>

<h3>Key PEPt Interfaces</h3>
<ul>

<li>{@link com.sun.corba.se.pept.transport.ContactInfoList ContactInfoList}
    - Client-side address selection mechanism and factory for
    alternate encodings, protocols and transports (EPT).</li>

<li>{@link com.sun.corba.se.pept.transport.Acceptor Acceptor}
    - Server-side endpoint, addressing and factory for alternate EPTs.</li>

</ul>
</p>

<h3>PEPt Client-side Interfaces</h3>
<ul>
<li><b>Protocol</b>
  <ul>

  <li>{@link com.sun.corba.se.pept.protocol.ClientDelegate ClientDelegate}
  - The presentation block interacts with <code>ClientDelegate</code>
  to initiate and complete a message send (and a possible
  response). <code>ClientDelegate</code> is a "portability" interface,
  to allow different vendors to plug in their implementation into a
  standard presentation block.</li>

  <li>{@link com.sun.corba.se.pept.protocol.ClientRequestDispatcher
  ClientRequestDispatcher} - This interface controls the client-side
  dispatch for a given EPT.</li>

  </ul>
</li>
<li><b>Transport</b>
  <ul>

  <li>{@link com.sun.corba.se.pept.protocol.ContactInfoList
  ContactInfoList} - A list of <code>ContactInfo</code> associated
  with a <em>ClientDelegate</em></li>.

  <li>{@link com.sun.corba.se.pept.protocol.ContactInfoListIterator
    ContactInfoListIterator} - An iterator which chooses the "next"
    EPT-specific <code>ContactInfo</code>.</li>

  <li>{@link com.sun.corba.se.pept.protocol.ContactInfoList
  ContactInfo} - <em><b>The key PEPt client-side interface.</b></em> The
  presentation block uses a <code>ClientDelegate</code> to select an
  EPT-specific <code>ContactInfo</em>.  That <code>ContactInfo</em>
  serves as a factory for EPT-specifc
  <code>ClientRequestDispatcher</code>,
  <code>Input/OutputObjects</code> and <code>Connection</code>.</li>

  </ul>
</li>
</ul>
</p>

<h3>PEPt Server-side Interfaces</h3>
<ul>
<li><b>Protocol</b>
  <ul>

  <li>{@link com.sun.corba.se.pept.protocol.ServerRequestDispatcher
  ServerRequestDispatcher} - This interface controls the server-side
  dispatch for a given EPT.</li>

  </ul>
</li>
<li><b>Transport</b>
  <ul>

  <li>{@link com.sun.corba.se.pept.protocol.Acceptor Acceptor}
  - <em><b>The key PEPt server-side interface.</b></em> <code>Aceptor</code>
  serves as a factory for EPT-specifc
  <code>ServerRequestDispatcher</code>,
  <code>Input/OutputObjects</code> and <code>Connection</code>.</li>

  </ul>
</li>
</ul>
</p>

<h3>PEPt Client and Server Interfaces</h3>
<ul>
<li><b>Presentation</b>
  <ul>

  <li>PEPt, at this time, does not provide interfaces for the
  presentation level.  PEPt is the architecture underlying Sun's CORBA
  implementation.  In that implementation the CORBA system provides
  stubs, ties, DII and DSI presentation artifacts that interact with
  the underlying PEPt interfaces.</li>

  </ul>
</li>
<li><b>Encoding</b>
  <ul>

  <li>{@link com.sun.corba.se.pept.encoding.InputObject InputObject}
  - The presentation block uses an <code>InputObject</code> to
  retrieve programming language typed data from encoded data sent in a
  message.</li>

  <li>{@link com.sun.corba.se.pept.encoding.OutputObject OutputObject}
  - The presentation block uses an <code>OutputObject</code> to
  post programming language typed data to be encoded and sent in a
  message.</li>

  </ul>
</li>
<li><b>Protocol</b>
  <ul>

  <li>{@link com.sun.corba.se.pept.protocol.MessageMediator MessageMediator}
  - A "repository" of data associated with a message to be sent or one
  received.  It is the main object used as an argument for methods of
  the interfaces of the PEPt architecture.</li>

  <li>{@link com.sun.corba.se.pept.protocol.ProtocolHandler ProtocolHandler}
  - Used to determine an incoming message and dispatch it
  appropriately.</li>

  </ul>
</li>
<li><b>transport</b>
  <ul>

  <li>{@link com.sun.corba.se.pept.protocol.Connection Connection}
  - The top-level abstraction of a "connection" between two PEPt
  peers.  Concreate instances may be TCP/IP sockets, Solaris Doors,
  Shared Memory, ATM, etc.</li>

  </ul>
</li>
</ul>
</p>

<h2>High-level view of PEPt Operation</h2>

<h3>PEPt Client-side Operation</h3>

<ol>
<li> Presentation asks <code>ClientDelegate</code> for an
<code>OutputObject</code>.</li>
  <ol>
  <li> <code>ClientDelegate</code> gets an EPT-specific
  <code>ContactInfo</code>.</li>
  <li> <code>ClientDelegate</code> uses the chosen
  <code>ContactInfo</code> as a factory to get an EPT-specific
  <code>ClientRequestDispatcher</code>.</li>
  <li> <code>ClientDelegate</code> transfers control to the
  EPT-specific <code>ClientRequestDispatcher.beginRequest</code>.
    <ol>
    <li> <code>ClientRequestDispatcher.beginRequest</code> uses
    <code>ContactInfo</code> as a factory to get EPT-specific
    <code>OutputObject</code>, <code>MessageMediator</code> and
    <code>Connection</code>.</li>
    <li> <code>ClientRequestDispatcher.beginRequest</code> may marshal
    or set header information on the <code>OutputObject</code> and it
    may execute interceptors (which may add additional header
    information) before returning the <code>OutputObject</code> to the
    presentation block. </li>
    </ol>
  </ol>
<li> Presentation block sets data objects to be sent by calling
<code>OutputObject</em> methods.</li>
<li> Presentation block signals the PEPt architecture to send the
message by calling
<code>ClientRequestDispatcher.marshalingComplete</code>.</li>
<li> <code>ClientRequestDispatcher.marshalingComplete</code> sends the
headers and data encoded in <code>OutputObject</code> on the
<code>Connection</code>. </li>
<li> Depending on the EPT,
<code>ClientRequestDispatcher.marshalingComplete</code> may return
immediately (i.e., an asynchronous message send with no
acknowledgment), may wait to get an indication that the message send
was successfully (i.e., an acknowledged asynchronous send) or wait for
a response (a synchronous message send). The following steps assume
waiting for a response.</li>
<li> <code>ClientRequestDispatcher.marshalingComplete</code> waits for a
response.  This may mean blocking on a read of the
<code>Connection</code> (e.g., SOAP/HTTP), or putting the client
thread to sleep while another thread demultiplexes replies (e.g.,
RMI-IIOP), or using the client thread itself to perform the
server-side operation (e.g., colocation optimization).</li>
<li> When a response arrives on the <code>Connection</code> it gives
the raw bits of the response to <code>ContactInfo</code> which creates
an EPT-specific <code>InputObject</code> and calls
<code>ProtocolHandler.handleRequest</code> to determine the message
type.</li>
  <ol>
  <li> <code>ProtocolHandler.handleRequest</code> determines the
  message type (e.g., Request, Response, Error, Cancel, Close, ...).</li>
  <li> Suppose it is a response to an RMI-IIOP request.  In that case
  it would find the thread and <code>MessageMediator</code> which
  originated the request and wake it up, after having passed it the
  response <code>InputObject</code>.</li>
  </ol>
<li> <code>ClientRequestDispatcher.marshalingComplete</code> may run
interceptors and use reply header metadata befor returning control to
the presentation block.</li>
<li> The presentation block call to
<code>ClientRequestDispatcher.marshalingComplete</code> would return
the response <code>InputObject</code>.</li>
<li> The presentation block would get response data objects from the
<code>InputObject</code>.</li>
<li> The presentation block would signal the PEPt architecture that
the invocation is complete by calling
<code>ClientRequestDispatcher.endRequest</code>.</li>
<li> <code>ClientRequestDispatcher.endRequest</code> may clean up
resources used in the invocation.</li>
</ol>

<h3>PEPt Server-side Operation</h3>

<p> Suppose a server support several EPTs.</p>

<ol>
<li> For each EPT, register an <code>Acceptor</code>.</li>
<li> If the system supports the concept of an "object reference" then
the <code>Acceptor</code> is responsible for adding its EPT
information (e.g., address information) to the object reference.</li>
<li> The <code>Acceptor</code> acts as a "listener" for client
connection requests.</li>
<li> When the <code>Acceptor</code> receives a connection request it
creates an EPT-specific <code>Connection</code> on which to receive
messages.</li>
<li> When <code>Connection</code> receives a message, it gives the raw
bits of the message to <code>Acceptor</code> which creates an
EPT-specific <code>InputObject</code> and calls
<code>ProtocolHandler.handleRequest</code> to determine the message
type.</li>
  <ol>
  <li> <code>ProtocolHandler.handleRequest</code> determines the
  message type.</li>
  <li> Suppose it is a request. In that case it would read enough
  header information to give to <code>Acceptor</code> to get an
  EPT-specific <code>InputObject</code>,
  <code>ServerRequestDispatcher</code> and <code>MessageMediator</code>.</li>
  <li> Control would then transfer to
  <code>ServerRequestDispatcher.dispatch</code>.</li>
    <ol>
    <li> <code>ServerRequestDispatcher.dispatch</code> uses header
    information to obtain appropriate presentation block artifacts
    (e.g., Ties, DSI handlers).</li>
    <li> As an example, a Tie would be given the <code>InputObject</code>.</li>
      <ol>
      <li> The Tie would get the request data from the
      <code>InputObject</code> and make it available to user
      code.</li>
      <li> In the case of a synchronous message, the Tie would ask the
      <code>ServerRequestDispatcher</code> for an
      <code>OutputObject</code>.</li>
        <ol>
        <li> The <code>ServerRequestDispatcher</code> would use the
	<code>Acceptor</code> as a factory to create the EPT-specific
	<code>OutputObject</code>.</li>
        </ol>
      <li> The Tie would set the response data (normal or error) on
      the <code>OutputObject</code>. </li>
      </ol>
    <li> <code>ServerRequestDispatcher.dispatch</code> would send the
    header and response data encoded in <code>OutputObject</code> on
    the <code>Connection</code>.</li>
    </ol>
    <li> <code>ServerRequestDispatcher.dispatch</code> may clean up
    any resources used in the invocation.</li>
    </ol>
  </ol>
</ol>

<h2>Initial ContactInfo and Acceptor Creation</h2>

<p> <code>ContactInfo</code> and <code>Acceptor</code> are the
factories for all other objects involved in a message for a particular
EPT. The question naturally arises, how are these created?</p>

<ul>
<li> From a tool reading service descriptions (e.g., WSDL). </li>
<li> By reading the contents of an object reference (e.g., CORBA IOR). </li>
<li> From a configuration file. </li>
</ul>

<h2>Other PEPt Interfaces</h2>

<ul>
<li>{@link com.sun.corba.se.pept.broker.Broker Broker} - A repository
of resources such as transport managers, thread pools, thread local
data structures, etc.</li>
</ul>

</body>
</html>