Hi, everyone. Our work on the Proton C++ API has progressed quite a bit, and it's time to talk about the changes.
First, a confession. I described the API we delivered in 0.12.0 as "substantially settled", excepting some of the extension APIs and those API elements that were hidden in the API docs. Our work since then has now exceeded what one can reasonably allow inside the confines of "substantially settled". I'll try to detail the changes and their rationales. After that I'll talk about our plan moving forward. There have also been many additions that do not affect API compatibility. I won't list all of those here, but you can explore them on the API spec. http://home.apache.org/~jross/pumpjack/index.html Before I enumerate the changes, however, I'd like to say that we really very much appreciate the use and feedback we've received on the API so far. It is absolutely invaluable, we're grateful, and we want more. ## Event handling http://home.apache.org/~jross/pumpjack/core/handler/index.html - Handler callback signatures - The handler callbacks now take relevant objects as inputs - We removed event (the arg and the API type) - In each callback, the first input argument is an entry-point into the endpoint object tree and can be used for navigation to parent objects such as container - We renamed on-start and on-stop to on-container-start and on-container-stop; these now take container - We removed on-unhandled - We renamed on-unhandled-error to simply on-error You can see the effect on the examples here: https://github.com/apache/qpid-proton/blob/master/examples/cpp/helloworld.cpp https://github.com/apache/qpid-proton/tree/master/examples/cpp ## Message http://home.apache.org/~jross/pumpjack/core/message/index.html - We renamed "address" to "to", retaining "address" as an alias; "to" matches the AMQP spec and better illustrates the relation to "reply-to" - We renamed application-properties to properties; "properties" is used in the sense of application-supplied properties throughout the API ## Sender and receiver instead of link http://home.apache.org/~jross/pumpjack/core/sender/index.html http://home.apache.org/~jross/pumpjack/core/receiver/index.html - We previously offered properties and methods on link that were useful only if the link was a receiver or vice versa; instead we now provide only the relevant members on sender and receiver respectively - This is reflected in the event handlers as well: there are now dedicated handler methods for senders versus receivers - Sender and receiver options are split accordingly ## Source and target instead of terminus http://home.apache.org/~jross/pumpjack/core/source/index.html http://home.apache.org/~jross/pumpjack/core/target/index.html - Same story as sender and receiver; source and target now contain no context-dependent members - Source and target options are split accordingly ## Tracker and delivery^r instead of delivery http://home.apache.org/~jross/pumpjack/core/tracker/index.html http://home.apache.org/~jross/pumpjack/core/delivery/index.html - Delivery was previously used for both the sending and receiving sides of a transfer; it is now separated for the same reasons as sender and receiver, source and target - A tracker is associated with sending: it tracks a message transfer from the sender's perspective - A delivery (in the revised sense) is a message transfer being received ## Flow control http://home.apache.org/~jross/pumpjack/core/receiver/index.html#flow-control - We now use API names that speak in terms of credit: receiver.credit, receiver.add-credit, sender.credit, receiver-options.credit-window ## Endpoint properties and methods http://home.apache.org/~jross/pumpjack/core/connection/index.html#endpoint-lifecycle - We introduced boolean properties for endpoint states instead of the endpoint.state bit field - Endpoint.close takes an optional error-condition ## Endpoint options http://home.apache.org/~jross/pumpjack/core/connection-options/index.html http://home.apache.org/~jross/pumpjack/core/session-options/index.html http://home.apache.org/~jross/pumpjack/core/sender-options/index.html http://home.apache.org/~jross/pumpjack/core/receiver-options/index.html - Connection.virtual-host instead of host, to clarify its purpose versus the host info supplied in URLs - Connection.max-sessions instead of max-channels, in order to speak in user terms, not AMQP spec terms - Added session-options - Some 0.12.0 link options will be removed until their status is decided ## Data types http://home.apache.org/~jross/pumpjack/types/index.html - We have dropped the "amqp-" prefixes from type names; if a language-provided type fits the need, we use that; if the language doesn't offer one, we can introduce the type without any concern about collisions - We will use string, not the URL class, as the first-class representation of a URL in API signatures; we will continue to use the URL class directly in our examples to simplify simple parsing jobs ## Future plans We have either already made or will be making these changes for Proton 0.13.0. The amount of outstanding work may require a Proton release delay. As with 0.12.0, not all parts of the API will be declared stable at that point. Specifically: - We will mark some elements of the API experimental and subject to change; for instance, the IO and codec namespaces will remain experimental - We will mark some elements internal (and thus not exposed in API docs) until we are confident they are ready for broader use Apart from these exclusions, however, we will be supporting the Proton 0.13.0 C++ core and data types as stable API going forward. Please give us your thoughts on the proposed API. We'll do our best to explain our thinking or adapt it. Thanks, Justin
