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

## Related Documentation

For papers, slides and examples of the PEPt architecture, please see:

- Harold Carr's Sun internal PEPt web page

## PEPt Architecture

PEPt stands for:

- Presentation: the data types that may be passed and the APIs used to interact with the remoting system.
- Encoding: the process of transforming those programming language data types into an underlying "wire" representation (and the wire representation itself).
- Protocol: The metadata which accompanies a message and the use of that metadata.
- transport: The mechanism used to move the encoded data and metadata from one location to another.

### Key PEPt Interfaces

- {@link com.sun.corba.se.pept.transport.ContactInfoList ContactInfoList} - Client-side address selection mechanism and factory for alternate encodings, protocols and transports (EPT).
- {@link com.sun.corba.se.pept.transport.Acceptor Acceptor} - Server-side endpoint, addressing and factory for alternate EPTs.

### PEPt Client-side Interfaces

- Protocol
  - {@link com.sun.corba.se.pept.protocol.ClientDelegate ClientDelegate} - The presentation block interacts with `ClientDelegate` to initiate and complete a message send (and a possible response). `ClientDelegate` is a "portability" interface, to allow different vendors to plug in their implementation into a standard presentation block.
  - {@link com.sun.corba.se.pept.protocol.ClientRequestDispatcher ClientRequestDispatcher} - This interface controls the client-side dispatch for a given EPT.
- Transport
  - {@link com.sun.corba.se.pept.protocol.ContactInfoList ContactInfoList} - A list of `ContactInfo` associated with a ClientDelegate
  .
  - {@link com.sun.corba.se.pept.protocol.ContactInfoListIterator ContactInfoListIterator} - An iterator which chooses the "next" EPT-specific `ContactInfo`.
  - {@link com.sun.corba.se.pept.protocol.ContactInfoList ContactInfo} - The key PEPt client-side interface. The presentation block uses a `ClientDelegate` to select an EPT-specific `ContactInfo. That `ContactInfo serves as a factory for EPT-specifc `ClientRequestDispatcher`, `Input/OutputObjects` and `Connection`.``

### PEPt Server-side Interfaces

- Protocol
  - {@link com.sun.corba.se.pept.protocol.ServerRequestDispatcher ServerRequestDispatcher} - This interface controls the server-side dispatch for a given EPT.
- Transport
  - {@link com.sun.corba.se.pept.protocol.Acceptor Acceptor} - The key PEPt server-side interface. `Aceptor` serves as a factory for EPT-specifc `ServerRequestDispatcher`, `Input/OutputObjects` and `Connection`.

### PEPt Client and Server Interfaces

- Presentation
  - 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.
- Encoding
  - {@link com.sun.corba.se.pept.encoding.InputObject InputObject} - The presentation block uses an `InputObject` to retrieve programming language typed data from encoded data sent in a message.
  - {@link com.sun.corba.se.pept.encoding.OutputObject OutputObject} - The presentation block uses an `OutputObject` to post programming language typed data to be encoded and sent in a message.
- Protocol
  - {@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.
  - {@link com.sun.corba.se.pept.protocol.ProtocolHandler ProtocolHandler} - Used to determine an incoming message and dispatch it appropriately.
- transport
  - {@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.

## High-level view of PEPt Operation

### PEPt Client-side Operation

1. Presentation asks `ClientDelegate` for an `OutputObject`.

1. `ClientDelegate` gets an EPT-specific `ContactInfo`.
2. `ClientDelegate` uses the chosen `ContactInfo` as a factory to get an EPT-specific `ClientRequestDispatcher`.
3. `ClientDelegate` transfers control to the EPT-specific `ClientRequestDispatcher.beginRequest`.
   1. `ClientRequestDispatcher.beginRequest` uses `ContactInfo` as a factory to get EPT-specific `OutputObject`, `MessageMediator` and `Connection`.
   2. `ClientRequestDispatcher.beginRequest` may marshal or set header information on the `OutputObject` and it may execute interceptors (which may add additional header information) before returning the `OutputObject` to the presentation block.

2. Presentation block sets data objects to be sent by calling `OutputObject methods.`
3. Presentation block signals the PEPt architecture to send the message by calling `ClientRequestDispatcher.marshalingComplete`.
4. `ClientRequestDispatcher.marshalingComplete` sends the headers and data encoded in `OutputObject` on the `Connection`.
5. Depending on the EPT, `ClientRequestDispatcher.marshalingComplete` 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.
6. `ClientRequestDispatcher.marshalingComplete` waits for a response. This may mean blocking on a read of the `Connection` (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).
7. When a response arrives on the `Connection` it gives the raw bits of the response to `ContactInfo` which creates an EPT-specific `InputObject` and calls `ProtocolHandler.handleRequest` to determine the message type.

1. `ProtocolHandler.handleRequest` determines the message type (e.g., Request, Response, Error, Cancel, Close, ...).
2. Suppose it is a response to an RMI-IIOP request. In that case it would find the thread and `MessageMediator` which originated the request and wake it up, after having passed it the response `InputObject`.

8. `ClientRequestDispatcher.marshalingComplete` may run interceptors and use reply header metadata befor returning control to the presentation block.
9. The presentation block call to `ClientRequestDispatcher.marshalingComplete` would return the response `InputObject`.
10. The presentation block would get response data objects from the `InputObject`.
11. The presentation block would signal the PEPt architecture that the invocation is complete by calling `ClientRequestDispatcher.endRequest`.
12. `ClientRequestDispatcher.endRequest` may clean up resources used in the invocation.

### PEPt Server-side Operation

Suppose a server support several EPTs.

1. For each EPT, register an `Acceptor`.
2. If the system supports the concept of an "object reference" then the `Acceptor` is responsible for adding its EPT information (e.g., address information) to the object reference.
3. The `Acceptor` acts as a "listener" for client connection requests.
4. When the `Acceptor` receives a connection request it creates an EPT-specific `Connection` on which to receive messages.
5. When `Connection` receives a message, it gives the raw bits of the message to `Acceptor` which creates an EPT-specific `InputObject` and calls `ProtocolHandler.handleRequest` to determine the message type.

1. `ProtocolHandler.handleRequest` determines the message type.
2. Suppose it is a request. In that case it would read enough header information to give to `Acceptor` to get an EPT-specific `InputObject`, `ServerRequestDispatcher` and `MessageMediator`.
3. Control would then transfer to `ServerRequestDispatcher.dispatch`.

1. `ServerRequestDispatcher.dispatch` uses header information to obtain appropriate presentation block artifacts (e.g., Ties, DSI handlers).
2. As an example, a Tie would be given the `InputObject`.

1. The Tie would get the request data from the `InputObject` and make it available to user code.
2. In the case of a synchronous message, the Tie would ask the `ServerRequestDispatcher` for an `OutputObject`.

1. The `ServerRequestDispatcher` would use the `Acceptor` as a factory to create the EPT-specific `OutputObject`.

3. The Tie would set the response data (normal or error) on the `OutputObject`.

3. `ServerRequestDispatcher.dispatch` would send the header and response data encoded in `OutputObject` on the `Connection`.

4. `ServerRequestDispatcher.dispatch` may clean up any resources used in the invocation.

## Initial ContactInfo and Acceptor Creation

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

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

## Other PEPt Interfaces

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