Re: New Ruby bindings...

[Gordon Sim <gs...@redhat.com>]

On 05/31/2011 07:57 PM, Darryl L. Pierce wrote:
> On Friday I spoke with Ted Ross for a bit about doing a more Ruby-esque
> set of bindings for the Qpid APIs. The APIs wouldn't be a replacement
> for the ones generated by SWIG, but would instead be a wrapper around
> them that feels more like a Ruby API.
>
> I've done an initial stab at this, creating several new class:
>
> Qpid::Messaging::Connection

What is the purpose of 'attr_accessor :connection_impl' (likewise for 
session_impl etc)?

In convert_options, the c++ client (as of 0.10 release) now supports the 
underscore based variants as synonyms (for uniformity with python).

> Qpid::Messaging::Session

The create_sender() method treats the options as applying to the address:

    # Creates a new endpoint for sending messages.
    def create_sender(address, options = {})
      address = "#{address};{create:always}" if options[:create] == :always
      Qpid::Messaging::Sender.new(@session_impl.createSender(address))
    end

I can see that this is a useful way of dynamically building addresses. 
However to me it would be better to have an address abstraction for 
that, so you would do something like:

   session.create_sender(address("my-topic", "my-subject", {create: 
always}))

Certainly it needs to be clear what address means in the method as is. 
If it had other options in it then the result would likely be an 
unparseable address.

One of the key motivations for the address string approach was to allow 
the same addresses/config to be used in applications of different 
languages. While I fully accept that specific languages may be able to 
offer additional simplifying constructs, we don't want to lose that 
basic uniformity either.

I assume that whatever create_sender does, create_receiver would 
eventually follow.

We should sync up the clients on acknowledge/reject. Python and c++ 
currently don't quite match here and it would be good to reach agreement 
on one approach that we can then move towards in all languages.

> Qpid::Messaging::Sender
> Qpid::Messaging::Receiver

Sender/Receiver don't expose capacity, unsettled and available. The 
send() method doesn't have a sync flag, the fetch() method doesn't have 
a timeout.

There are also no methods for getting the session for a given 
sender/receiver, or the connection for a given session. (Or indeed for 
retrieving existing sessions, sender or receivers by name).

Are these merely issues in completeness or is this intentional 
simplification?

> Qpid::Messaging::Message

I'm not sure amqp/string is needed as a content type. It think an 
existing content type would be better in most cases (e.g. text/plain or 
some other specific binary format if the data is not text). It certainly 
shouldn't be the default as none of the other clients use or recognise 
that as anything special.

> which you can look at in my Github repo[1].
>
> I'd like some feedback on the design so far.

I think it would be worth listing out the specific things that could be 
more Ruby like.

E.g. exposing the options more directly seems like a perfect example of 
the sort of thing that you would want in the exposed API, likewise the 
built in support for content types (both features the python API has for 
example where the c++ is more limited).

My assumption is that other than specific rubyisms we would want to be 
pretty close to the existing python (and less so the C++) API. Hence 
listing those rubyisms explicitly helps focus the debate.

---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:users-subscribe@qpid.apache.org

Re: New Ruby bindings...

["Darryl L. Pierce" <dp...@redhat.com>]

On Fri, Jun 03, 2011 at 12:12:26PM +0100, Gordon Sim wrote:
> On 05/31/2011 07:57 PM, Darryl L. Pierce wrote:
> >On Friday I spoke with Ted Ross for a bit about doing a more Ruby-esque
> >set of bindings for the Qpid APIs. The APIs wouldn't be a replacement
> >for the ones generated by SWIG, but would instead be a wrapper around
> >them that feels more like a Ruby API.
> >
> >I've done an initial stab at this, creating several new class:
> >
> >Qpid::Messaging::Connection
> 
> What is the purpose of 'attr_accessor :connection_impl' (likewise
> for session_impl etc)?

Hrm, that should have been attr_reader and not allow modifying the
reference. I'll double-check and make sure that they're all attr_reader.

Primarily I wanted to allow the wrappers to have access to those
implementation details.

> In convert_options, the c++ client (as of 0.10 release) now supports
> the underscore based variants as synonyms (for uniformity with
> python).

Cool. I was going solely based on the headers in cpp/include/messaging.
It would be simpler to allow passing the options up using:

@options.each_pair {|key,value" "#{key.to_s}:#{value.to_s}"}

and not worry about explicitly mapping the values. This would also allow
the Ruby code to avoid duplicating the logic for what are valid options.
It only bothered with them now due to the hypens.

> >Qpid::Messaging::Session
> 
> The create_sender() method treats the options as applying to the address:
> 
>    # Creates a new endpoint for sending messages.
>    def create_sender(address, options = {})
>      address = "#{address};{create:always}" if options[:create] == :always
>      Qpid::Messaging::Sender.new(@session_impl.createSender(address))
>    end
> 
> I can see that this is a useful way of dynamically building
> addresses. However to me it would be better to have an address
> abstraction for that, so you would do something like:
> 
>   session.create_sender(address("my-topic", "my-subject", {create:
> always}))
> 
> Certainly it needs to be clear what address means in the method as
> is. If it had other options in it then the result would likely be an
> unparseable address.
> 
> One of the key motivations for the address string approach was to
> allow the same addresses/config to be used in applications of
> different languages. While I fully accept that specific languages
> may be able to offer additional simplifying constructs, we don't
> want to lose that basic uniformity either.

Okay, I think I grok that. I think I need a little more detail on what
are the options that make up the address in:

Sender createSender(const std::string& address)

so I can more accurately model it. 

> I assume that whatever create_sender does, create_receiver would
> eventually follow.

Yes, it will. The approach I took was to build up a code base for the
specific use case I had, which was a simple sender/receiver exchange.
Now that it does that, I'm working from the bottom up from Connection to
fill in the gaps in APIs.

> We should sync up the clients on acknowledge/reject. Python and c++
> currently don't quite match here and it would be good to reach
> agreement on one approach that we can then move towards in all
> languages.

What are the options? Right now I've written a binding for those APIs
that I've not tested out yet.

> >Qpid::Messaging::Sender
> >Qpid::Messaging::Receiver
> 
> Sender/Receiver don't expose capacity, unsettled and available. The
> send() method doesn't have a sync flag, the fetch() method doesn't
> have a timeout.
> 
> There are also no methods for getting the session for a given
> sender/receiver, or the connection for a given session. (Or indeed
> for retrieving existing sessions, sender or receivers by name).
> 
> Are these merely issues in completeness or is this intentional
> simplification?

Completeness. I'm only as far as Session in working up from Connection
to make the wrappers more complete.

> >Qpid::Messaging::Message
> 
> I'm not sure amqp/string is needed as a content type. It think an
> existing content type would be better in most cases (e.g. text/plain
> or some other specific binary format if the data is not text). It
> certainly shouldn't be the default as none of the other clients use
> or recognise that as anything special.
> 
> >which you can look at in my Github repo[1].
> >
> >I'd like some feedback on the design so far.
> 
> I think it would be worth listing out the specific things that could
> be more Ruby like.
> 
> E.g. exposing the options more directly seems like a perfect example
> of the sort of thing that you would want in the exposed API,
> likewise the built in support for content types (both features the
> python API has for example where the c++ is more limited).
> 
> My assumption is that other than specific rubyisms we would want to
> be pretty close to the existing python (and less so the C++) API.
> Hence listing those rubyisms explicitly helps focus the debate.

Good deal. I'm on PTO today but will write up something on Monday and
send that out.

-- 
Darryl L. Pierce, Sr. Software Engineer @ Red Hat, Inc.
Delivering value year after year.
Red Hat ranks #1 in value among software vendors.
http://www.redhat.com/promo/vendor/