C++ directory re-organization

[Alan Conway <ac...@redhat.com>]

https://issues.apache.org/jira/browse/QPID-243 describes a proposed
re-org to simplify building and using the C++ code. I'll be doing this
shortly after the 0-9 merge, get your comments in now.

Cheers,
Alan.

Re: C++ directory re-organization

[Alan Conway <ac...@redhat.com>]

On Mon, 2007-03-05 at 16:19 +0000, Rupert Smith wrote:
> I notice that you plan to rename files after classes? If you are doing
> a big rename, it might also be advantageous to try and rename towards
> having a consistent client API whilst you are at it. 

Not at this point - I'm just restoring the original simple
dir=namespace/file=class.cpp correspondance that got a bit mangled by
the autobuild changes.

> There are
> presently some pointless inconsistencies in naming accross the
> clients. For example:
> 
> java: AMQSession
> .net:  AmqChannel
> cpp: ClientChannel

Can  you please add your thoughts to QPID-342, which is about
refactoring of the C++ client API for binary compatibility. That would
be the time to make the changes you propose. 

Actually this probably merits a separate JIRA. Right now there's no
basis for me to do a renaming because there's no consensus on the
correct names. Also seems like we need broder agreement on API than just
class names if you want a meaningful cross-language API.

Like Gordon I am  not in favour of prefixes on identifiers when
namespaces are a better choice. I'm also not keen on calling a Channel a
Session - the word Session is nowhere used in AMQP 0-8, and it almost
certainly will be used in 0-10 with a very different meaning. I think
any agreed cross-language API must be based strictly on terms from the
AMQP protocol.

Anyhow if you want to start a JIRA for this, please link it to QPID-342
so I wont forget.

Cheers,
Alan.

Re: C++ directory re-organization

[Rupert Smith <ru...@googlemail.com>]

I couldn't care less what the names are, but I would really love to
see consistent naming accross all clients, (from packages right down
to method names). If you imagine someone writing a manual for Qpid, it
would be a real shame if that manual had to have a seperate Appendix
for each client. It should really just have one describing the common
abstract API that all implement in a semantically equivalent manner.

I'm going to shut up about this now though, shouldn't derail Alan's
original topic for the thread.

On 3/5/07, Robert Godfrey <ro...@gmail.com> wrote:
> >
> > FYI: The class name in c++ is just Channel. I wouldn't be in favour of a
> > 'amq[p]' style prefix as it doesn't add much value.
>
>
>
> Except horrific namespace clashes over commly used names like Session,
> Message, Method... etc :-)
>
> -- Rob
>

Re: Naming etc (was Re: C++ directory re-organization)

[Rupert Smith <ru...@googlemail.com>]

Yes, thats worth mentioning too. The JMS api will always be different
from the "close to the protocol" AMQ/QPID api. Currently the java
client provides both APIs, with JMS implemented on top of the QPID one
(more or less). The JMS API cannot be implemented in other lanaguges,
because Sun forbids it. The java will still need to expose the same
API as the other clients, because there are certain things you cannot
do from the pure JMS API.

I still think things will be easier if we begin steering towards a
unified API as early as possible. I only mentioned the idea now,
because I saw an opportunity piggy back this on top of a major
refactoring of the C++ that needs to be carried out anyway.

On 3/6/07, Robert Godfrey <ro...@gmail.com> wrote:
> The major issue is not the naming but the struture.  I agree that we should
> have some API which is common across the different languages which probably
> maps pretty closely to the AMQP protocol iteself (the protocol looking as
> much like an API as it is possible for a protocol to do).  However, for Java
> at least, we would expect that we would need a separate manual explaining
> how to use JMS over AMQP.
>
> I would agree this is something we want by the time we attempt to graduate
> from incubator status.  Right now I suggest we look more at the impact that
> future versions of AMQP may have on Qpid (in particular, given the changes
> that are likley in 0-10/0-11 I think it would be unwise to start solidifying
> an API just yet :-) )...
>
> -- Rob
> On 06/03/07, Rupert Smith <ru...@googlemail.com> wrote:
> >
> > I think we should be aiming to be identical in every respect in which
> > it is reasonable to do so. That is to say that, if there is not a very
> > good reason for the API being different among the clients, then why
> > make it different? There may need to be occasional differences to
> > cater for the conventions/type systems/other reasons relating to the
> > implementing technology. I'd like to see identical package/namespace
> > names (relative to a root), class names, method names, method
> > arguments, argument types, even the ordering of the arguments in
> > method calls, in so far as its possible within the different
> > languages. If I were looking at Qpid for the first time, this would
> > speak volumes to me about the unified, well integrated product that
> > Qpid is. The manual will only need to be written once (with examples
> > that easily translate). Are there any compelling reasons not to do
> > this?
> >
> > Also, if its to be done it should be done as early as possible. Before
> > there are too many clients coding to the different APIs that will be
> > very annoyed at having it refactored under their feet.
> >
> > Rupert
> >
> > On 3/6/07, Gordon Sim <gs...@redhat.com> wrote:
> > > Robert Godfrey wrote:
> > > > Indeed... But java code littered with disambiguating
> > > > org.apache.qpid.amqp.Session and javax.jms.Session sure does look ugly
> > :-)
> > > > ... now if only you could do aliasing you could call one AMQPSession
> > and
> > > > one
> > > > JMSSession ;-)
> > >
> > > I agree, it would be nice to be able to define alias type names or
> > > 'import as' or something in java. That's one reason that identical
> > > naming across several languages may be hard to agree on - each language
> > > brings a slightly different set of conventions and constraints into
> > play.
> > >
> > > Getting more consistent doesn't have to mean being identical in every
> > > respect though. Perhaps the place to start is at the structural level;
> > > deciding whether we want a low level AMQP API for each language,
> > > mirroring the protocol structure in effect and therefore more likely to
> > > be easily understood across different clients. I would certainly like to
> > > make the c++ and python clients more consistent, but haven't thought it
> > > all through yet.
> > >
> >
>

Re: Naming etc (was Re: C++ directory re-organization)

[Robert Godfrey <ro...@gmail.com>]

The major issue is not the naming but the struture.  I agree that we should
have some API which is common across the different languages which probably
maps pretty closely to the AMQP protocol iteself (the protocol looking as
much like an API as it is possible for a protocol to do).  However, for Java
at least, we would expect that we would need a separate manual explaining
how to use JMS over AMQP.

I would agree this is something we want by the time we attempt to graduate
from incubator status.  Right now I suggest we look more at the impact that
future versions of AMQP may have on Qpid (in particular, given the changes
that are likley in 0-10/0-11 I think it would be unwise to start solidifying
an API just yet :-) )...

-- Rob
On 06/03/07, Rupert Smith <ru...@googlemail.com> wrote:
>
> I think we should be aiming to be identical in every respect in which
> it is reasonable to do so. That is to say that, if there is not a very
> good reason for the API being different among the clients, then why
> make it different? There may need to be occasional differences to
> cater for the conventions/type systems/other reasons relating to the
> implementing technology. I'd like to see identical package/namespace
> names (relative to a root), class names, method names, method
> arguments, argument types, even the ordering of the arguments in
> method calls, in so far as its possible within the different
> languages. If I were looking at Qpid for the first time, this would
> speak volumes to me about the unified, well integrated product that
> Qpid is. The manual will only need to be written once (with examples
> that easily translate). Are there any compelling reasons not to do
> this?
>
> Also, if its to be done it should be done as early as possible. Before
> there are too many clients coding to the different APIs that will be
> very annoyed at having it refactored under their feet.
>
> Rupert
>
> On 3/6/07, Gordon Sim <gs...@redhat.com> wrote:
> > Robert Godfrey wrote:
> > > Indeed... But java code littered with disambiguating
> > > org.apache.qpid.amqp.Session and javax.jms.Session sure does look ugly
> :-)
> > > ... now if only you could do aliasing you could call one AMQPSession
> and
> > > one
> > > JMSSession ;-)
> >
> > I agree, it would be nice to be able to define alias type names or
> > 'import as' or something in java. That's one reason that identical
> > naming across several languages may be hard to agree on - each language
> > brings a slightly different set of conventions and constraints into
> play.
> >
> > Getting more consistent doesn't have to mean being identical in every
> > respect though. Perhaps the place to start is at the structural level;
> > deciding whether we want a low level AMQP API for each language,
> > mirroring the protocol structure in effect and therefore more likely to
> > be easily understood across different clients. I would certainly like to
> > make the c++ and python clients more consistent, but haven't thought it
> > all through yet.
> >
>

Re: Naming etc (was Re: C++ directory re-organization)

[Rupert Smith <ru...@googlemail.com>]

I think we should be aiming to be identical in every respect in which
it is reasonable to do so. That is to say that, if there is not a very
good reason for the API being different among the clients, then why
make it different? There may need to be occasional differences to
cater for the conventions/type systems/other reasons relating to the
implementing technology. I'd like to see identical package/namespace
names (relative to a root), class names, method names, method
arguments, argument types, even the ordering of the arguments in
method calls, in so far as its possible within the different
languages. If I were looking at Qpid for the first time, this would
speak volumes to me about the unified, well integrated product that
Qpid is. The manual will only need to be written once (with examples
that easily translate). Are there any compelling reasons not to do
this?

Also, if its to be done it should be done as early as possible. Before
there are too many clients coding to the different APIs that will be
very annoyed at having it refactored under their feet.

Rupert

On 3/6/07, Gordon Sim <gs...@redhat.com> wrote:
> Robert Godfrey wrote:
> > Indeed... But java code littered with disambiguating
> > org.apache.qpid.amqp.Session and javax.jms.Session sure does look ugly :-)
> > ... now if only you could do aliasing you could call one AMQPSession and
> > one
> > JMSSession ;-)
>
> I agree, it would be nice to be able to define alias type names or
> 'import as' or something in java. That's one reason that identical
> naming across several languages may be hard to agree on - each language
> brings a slightly different set of conventions and constraints into play.
>
> Getting more consistent doesn't have to mean being identical in every
> respect though. Perhaps the place to start is at the structural level;
> deciding whether we want a low level AMQP API for each language,
> mirroring the protocol structure in effect and therefore more likely to
> be easily understood across different clients. I would certainly like to
> make the c++ and python clients more consistent, but haven't thought it
> all through yet.
>

Naming etc (was Re: C++ directory re-organization)

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

Robert Godfrey wrote:
> Indeed... But java code littered with disambiguating
> org.apache.qpid.amqp.Session and javax.jms.Session sure does look ugly :-)
> ... now if only you could do aliasing you could call one AMQPSession and 
> one
> JMSSession ;-)

I agree, it would be nice to be able to define alias type names or 
'import as' or something in java. That's one reason that identical 
naming across several languages may be hard to agree on - each language 
brings a slightly different set of conventions and constraints into play.

Getting more consistent doesn't have to mean being identical in every 
respect though. Perhaps the place to start is at the structural level; 
deciding whether we want a low level AMQP API for each language, 
mirroring the protocol structure in effect and therefore more likely to 
be easily understood across different clients. I would certainly like to 
make the c++ and python clients more consistent, but haven't thought it 
all through yet.

Re: C++ directory re-organization

[Robert Godfrey <ro...@gmail.com>]

Indeed... But java code littered with disambiguating
org.apache.qpid.amqp.Session and javax.jms.Session sure does look ugly :-)
... now if only you could do aliasing you could call one AMQPSession and one
JMSSession ;-)

On 05/03/07, Gordon Sim <gs...@redhat.com> wrote:
>
> Robert Godfrey wrote:
> >>
> >> FYI: The class name in c++ is just Channel. I wouldn't be in favour of
> a
> >> 'amq[p]' style prefix as it doesn't add much value.
> >
> >
> >
> > Except horrific namespace clashes over commly used names like Session,
> > Message, Method... etc :-)
>
> Thats what namespaces are for :-)
>

Re: C++ directory re-organization

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

Robert Godfrey wrote:
>>
>> FYI: The class name in c++ is just Channel. I wouldn't be in favour of a
>> 'amq[p]' style prefix as it doesn't add much value.
> 
> 
> 
> Except horrific namespace clashes over commly used names like Session,
> Message, Method... etc :-)

Thats what namespaces are for :-)

Re: C++ directory re-organization

[Robert Godfrey <ro...@gmail.com>]

>
> FYI: The class name in c++ is just Channel. I wouldn't be in favour of a
> 'amq[p]' style prefix as it doesn't add much value.



Except horrific namespace clashes over commly used names like Session,
Message, Method... etc :-)

-- Rob

Re: C++ directory re-organization

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

Rupert Smith wrote:
> I notice that you plan to rename files after classes? If you are doing
> a big rename, it might also be advantageous to try and rename towards
> having a consistent client API whilst you are at it. There are
> presently some pointless inconsistencies in naming accross the
> clients. For example:
> 
> java: AMQSession
> .net:  AmqChannel
> cpp: ClientChannel

FYI: The class name in c++ is just Channel. I wouldn't be in favour of a 
'amq[p]' style prefix as it doesn't add much value.

Re: C++ directory re-organization

[Rupert Smith <ru...@googlemail.com>]

I notice that you plan to rename files after classes? If you are doing
a big rename, it might also be advantageous to try and rename towards
having a consistent client API whilst you are at it. There are
presently some pointless inconsistencies in naming accross the
clients. For example:

java: AMQSession
.net:  AmqChannel
cpp: ClientChannel

I wanted to mail about this before but decided to keep interop testing
and testing in general as my #1 background task (#1 foreground being
looking after internal clients for Marnie) and forget about the client
API for now. This is just a gentle hint to nudge you in that
direction...

Rupert

On 3/5/07, Alan Conway <ac...@redhat.com> wrote:
> https://issues.apache.org/jira/browse/QPID-243 describes a proposed
> re-org to simplify building and using the C++ code. I'll be doing this
> shortly after the 0-9 merge, get your comments in now.
>
> Cheers,
> Alan.
>
>