The changes look good overall, removing the event class makes the handler's API much cleaner IMO. I found the on_unhandled callback very useful for testing/debugging, when I didn't know what event to expect for my unit tests. Do you think there could be another way of setting a catchall for events? The obvious workaround would be to implement all callbacks but this is much more clunky.
Thanks Alexandre On Thu, Apr 14, 2016 at 8:06 PM, Justin Ross <[email protected]> wrote: > 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 >
