On 7 Feb 2011, at 17:00, Rajith Attapattu wrote:
So far I have only heard positive comments about this approach.
Does anybody have any concerns about the approach in general or any
comments
about how it should be done if it's needed ?
Well, not negative, but I *do* have some questions, which are
possibly just due to my lack of knowledge of existing documentation
and processes.
Basically, how are we going to ensure that this new API never gets
deprecated? Where do we state/promise these things? There isn't a
page of Javadoc on the Qpid site showing our fixed, stable, public
API sets. I'm aware of the docbook/PDF documentation and Java
programming guides, but I was thinking of something more formal.
Anyway, if we can make such a statement about your proposed API, why
can't we just make that same statement about AMQConnectionFactory,
and add some extra helper methods to it, as needed, documenting and
publishing as we go? I believe the effect would be identical...
In principle, I agree we need to set up some stable APIs but, why not
start off by documenting and improving the existing ones first, and
then add your proposed code in there?
I would suggest firstly deprecating AMQConnectionFactory entirely and
making a QpidConnectionFactory interface, and having some
implementations such as an AbstractQpidConnectionfractory parent and
then QpidJndiConnectionFactory, QpidPropertiesFileConnectionfactory
or QpidUrlConnectionFactory, and also a QpidConnectionFactoryHelper
class with your static methods. We then document the static methods
and the interface methods as public APIs, as well as any extra
methods provided by the other implementations. Note that this gets
rid of AMQP in the class name, which is, IMHO, a Bad Thing. I suspect
most of the API will probably consist of constructors, or maybe
static methods to get concrete implementations, and there's still a
few more things we need to think about here in terms of API design.
Does any of this fit in with your ideas at all?
If we do this properly, we can also improve our Spring integration,
since the org.apache.qpid.jndi.PropertiesFileInitialContextFactory is
a bit too generic, replacing it with the above factory concrete
implementations?
Other classes we need to expose with proper Javadoc documentation
would be the URL classes, which possibly need a bit of attention if
we want to add the new JMS URL syntax as well. These can maybe all
extend a generic QpidUrl class, with JmsUrl, BindingUrl, AddressUrl,
AmqpUrl or whatever as concrete implementations to choose from,
making it clear in the method signatures by accepting either a String
representation or the parent QpidUrl class. This is Future Work,
obviously, but it had occurred to me before and I don't know if I've
mentioned it?
Perhaps we should designate a package (or more?) which will only
contain public interfaces. Probably org.apache.qpid.jms is the right
place for these? Then we just generate javadocs for this at release
time, and keep the rest hidden. This helps with OSGi packaging too,
giving a source for a list of our exported packages for a client
bundle, the rest being private.
I am hoping to create a JIRA on this soon abd perhaps attach a
very simple
patch.
And if there are no objections, I will be tempted to commit it by
the end of
the week.
I'd like to make sure we get it right as we need to provide a stable
interface between releases going forward.
Therefore I urge all interested folks to voice in their concerns/
opinions at
the earliest possible.
Voiced.
I do like the idea of an API for creating connections, so a tentative
+1, or maybe a +0.5f, assuming we also make a start on publishing our
public APIs somewhere. A 'stable' API needs to be documented
somewhere permanently before it can be regarded as such.
See the ActiveMQ site for what I think we should be aiming for:
http://activemq.apache.org/maven/activemq-core/apidocs/org/apache/
activemq/ActiveMQConnectionFactory.html
Cheerz,
Andrew.
--
-- andrew d kennedy ? do not fold, bend, spindle, or mutilate ;
-- http://grkvlt.blogspot.com/ ? edinburgh : +44 7582 293 255 ;
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
