On Mon, Feb 7, 2011 at 6:55 PM, Andrew Kennedy < [email protected]> wrote:
> 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, Very good question. I have the same concern as yours for all our public APIs not just the java client. We do proclaim that we have a common Messaging API for all our non JMS clients (Ex. Python, C++, Perl ..etc) But no where in our website (or for that matter in our documentation) we specify what this common API is. I think we need to specify this prominently somewhere in our documentation. We could list our Java client extensions in the same location. > 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... > To begin with I don't think the AMQConnectionFactory is a good candidate to expose as a public interface as it is. There are many public methods in it that are unnecessary for our purpose and will only confuse users. There are also several helper methods that we may need to add like createDestination which will only make the ConnectionFactory implementation bloated. Also there can be more than one ConnectionFactory implementation in the code base. There has been some interest in one which can do connection pooling. We need to find a way to hide all these complexities behind a simple stable interface that can be easily maintained. Exposing the AMQConnectionFactory as it is will not cut it. > 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 am not against this at all. But I am not sure which of the existing ones are good candidates for being promoted as public interfaces (obviously after some rework) ? > > 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? > I think regardless of exposing a public interface or not, we probably need to do some refactoring along the lines you are proposing. The JMS client is certainly in need of some refactoring, especially the various AMQXXX classes. However IMO any of that work should be done with keeping 1.0 in mind. There are lots of ideas about how the restructuring should be and the timing etc.. That is why I think it's all the more important that we come up with a very simple interface where we can easily swap any implementation at any time without affecting our users. Exposing what we have now, might not help us here. > 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? > Integration with various containers is becoming increasingly important. There have been various queries about integrating into other jndi mechanisms, various app servers, ESB's, containers like spring etc.. Therefore we need to consider all these possibilities when designing our interface. > 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? > I think just like the common addressing scheme, we need to come up with a common connection URL format across all clients. I don't know understand why we need a client specific url. > > 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 agree with you here. However the above package contains all kinds of classes that probably needs to move out to a suitable location. > > 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. > > Totally agree with you. Again, I think this should be the case for all our clients, not just the Java client. > 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] > > -- Regards, Rajith Attapattu Red Hat http://rajith.2rlabs.com/
