Mailing-List: contact users-help@qpid.apache.org; run by ezmlm
Precedence: bulk
Reply-To: users@qpid.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CANVjZ_TCZW3=gTNHrVL0bwJY42m=Y=GTi_bT71QS29w19w0e8A@mail.gmail.com>
References: 
 <CANVjZ_TCZW3=gTNHrVL0bwJY42m=Y=GTi_bT71QS29w19w0e8A@mail.gmail.com>
Date: Fri, 15 Apr 2016 19:29:34 +0200
Message-ID: 
 <CAPAiS1JitcYAZ83=1u0zOy7zPcrUjy7hD-P-Dg+-xtftUk_QHA@mail.gmail.com>
Subject: Re: Proton C++ API update
From: Alexandre Trufanow <alexandre.trufanow.mx@gmail.com>
To: users@qpid.apache.org
Content-Type: multipart/alternative; boundary=001a113cd9a6b924f70530895aba

--001a113cd9a6b924f70530895aba
Content-Type: text/plain; charset=UTF-8

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 <justin.ross@gmail.com> 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
>

--001a113cd9a6b924f70530895aba--