THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
This document (in progress) describes the detailed architecture of the proton library. At its heart, proton provides a protocol engine that implements the AMQP 1.0 protocol specification. The concept of a Protocol Engine is central to the proton library, so please read the Protocol Engines document for some important background, in particular the concepts of the top half and the bottom half of a protocol engine.
The UML diagram below contains a relatively complete model of the engine API, along with the dividing line between its top and bottom halves. At its core a protocol engine is simply modelling the endpoint state machine defined by a given protocol specification, in this case the AMQP 1.0 specification. As such it should be no surprise that the top half of the engine API corresponds quite directly to entities defined within the AMQP specification itself. I'll describe each of these briefly here, but ultimately a good familiarity with the AMQP 1.0 specification is helpful to fully understand the API in depth.
Endpoints: Connections, Sessions, and Links
These objects capture protocol endpoint state. An endpoint is an entity responsible for remembering key state for a given participant in a multi-way conversation. Connections, Sessions, and Links are all endpoints. Links track all the conversational state relating to message transfer between a specific Source and Target. There can be multiple Links established simultaneously on a single Session, and multiple Sessions established simultaneously on a single Connection, therefore each Connection endpoint may contain multiple Session endpoints, and likewise each Session endpoint may contain multiple Link endpoints At any given point in time a Connection endpoint will be associated with at most one TCP Connection (see Transport).
Every endpoint object may be in one of three states: UNINIT, ACTIVE, and CLOSED. The open(), close(), and reset() methods transition the endpoint between these states as depicted in the diagram below. Each endpoint additionally tracks the last known state of the remote endpoint.
Endpoint objects are created in one of two scenarios. In the most basic case the local application directly triggers creation of an endpoint object in order to initiate the given type of conversation (Connection, Session, or Link). In the case of Sessions and Links, the remote application might trigger the engine to internally create an endpoint. The local and last known remote endpoint state may be used to distinguish between the various scenarios. In total there are 9 possible combinations of these states described in more detail in the table below.
| Local | Remote | Description |
|---|---|---|
| UNINIT | UNINIT | This would be the initial state of an endpoint that is newly created by the local application. |
| UNINIT | ACTIVE | This would be the initial state of an endpoint that was created by the engine in response to actions taken by the remote application.It can be thought of as "half open". |
| UNINIT | CLOSED | Same as the above except the remote application has chosen to close its own endpoint prior to reaching a fully established state, i.e. the remote application is aborting. |
| ACTIVE | UNINIT | Locally initiated "half open". |
| ACTIVE | ACTIVE | Pairing between the two endpoints is fully established. |
| ACTIVE | CLOSED | In the process of a remotely initiated closing. (Half closed). |
| CLOSED | UNINIT | In the process of a locally initiated abort. |
| CLOSED | ACTIVE | In the process of a locallly initiated closing. (Half Closed) |
| CLOSED | CLOSED | Fully closed. |
Deliveries
In addition to holding the common endpoint state described above, Link endpoints also track the state of messages in the process of being transferred between a designated Source and Target. Each message transfer is associated with a Delivery object, and the Link endpoint internally keeps an ordered set of these objects. Depending on the directionality of the given Link endpoint (Receiver vs Sender), the Deliveries are kept in either incoming or outgoing order. Each Link endpoint also tracks the current delivery. The Receiver.recv() and Sender.send() methods may be used to access/supply message data for the current delivery.
Messenger
