Cleaning up the .NET Client public Interface

[Tomas Restrepo <to...@devdeo.com>]

I've been working long enough now on the .net client that I know my way
around the code a bit (or parts of it, at least :)), and I've been working
on actually using it for some things.

One of the things that I've noticed is that the public interface the client
exposes to the developer (at least the part that matters) is a bit messy at
this moment. I think that we're running a bit late, but if we don't clean it
up a bit now, down the road is going to be pretty hard to do once more
people take a hard dependency on the current interface.

Now, let me say up front I understand the reasons why the interface is like
this. It is based (very loosely) on the original JMS interface for the java
client (though the java interface is a bit more evolved now). That by itself
is not a problem and it is not something I'm concerned with.

Instead, I'm somewhat concerned that the interface feels pretty clunky at
times, it is not very ".NET" oriented (i.e. doesn't quite follow the
platform idioms) and that it really suffers from a number of shortcomings
that would be interesting to fix.

So here's an initial list of some of the things I've found that would be
candidates for cleaning up

1- The core classes of the API don't agree with their corresponding
interfaces very well. This is particularly bad for IConnection vs.
AMQConnection, in which the former is pretty useless as it is because it
leaves out a number of important things, while the latter exposes a whole
bunch of extra public methods that pop up all over the place and that
clients should not really be using. 

For example, the methods controlling the Heartbeat threads are all public,
while, imho, this should only be controlled by the library itself.

2- Use of delegates instead of events: In a number of places, delegates are
used as notification mechanisms. That would be fine, except that exposing
delegates as properties or public fields is a pretty bad practice because
anyone can invoke them or complete clear the invocation lists (i.e. a bad
developer can abuse them). They really should be converted to events instead
of simple delegates. 

Candidates here include IConnection.ExceptionListener (which really should
be renamed to match the change from the Java interface-based API!) as well
as IMessageConsumer.OnMessage (which again, needs to be renamed). And while
at it, they should really follow the standard delegate signatures for
events. 

It may not sound like a bit deal, but it's important in getting the library
to look like it was written for .net in the first place.

3- Loose the Set-only properties. What's up with that? ;)

4- Simplify IChannel: it simply has too many responsabilities and overloads.
For example, I think we should really get rid of message creation from here
and put it somewhere else, get rid of CreateFieldTable, as well as loose
CreateConsumer/CreateProducer and leave only the consumer/producer builders
(but rename CreateXXXBuilder(), which is very confusing)

I'm sure I'm missing more, but these would go a long way by themselves. It's
also possible that maybe we need a more significant refactoring of the
public interface in other to simplify it (or maybe a simpler api on top of
it, I'm not sure yet). 

Of course I'm aware some people (JPMC?) have applications built on top of
the current API and changes like the ones I'm mentioning would affect them,
but I thought I might as well throw it out there and see how people feel
about it.

Any comments?

(P.S: Besides this there are a bunch of issues with the internal API that
could use with some heavy refactoring, but that's a topic for another
thread).

Tomas Restrepo
http://www.winterdom.com/weblog/