Discuss: AMQNET-93

[e....@gmail.com]

This message is to open up a discussion to the developer forum to gather a  
wider range of feedback from the developer community that may not be  
monitoring the JIRA database.

For background, please refer to  
https://issues.apache.org/activemq/browse/AMQNET-93.

Following are my comments in response to Yev's and Tim's comments:

The comments about the naming convention are valid, but I think there are  
more compelling reasons for going with the NMS prefix convention.

There's not much that can be done in regards to Microsoft's .Net framework  
guidelines. To suddenly start changing to use Nms instead of NMS would only  
create confusion. The use of all-caps NMS is well established in the  
product. If we want to switch from NMS to Nms, then that should be  
discussed and changed in a consistent manner rather than letting  
inconsistencies creep into the codebase.

If the NMS prefix were redundant with the NMS namespace, then no classes  
would have this prefix. The NMSException class would simply be called  
Exception, likewise with the NMSSecurityException class. It has to be  
considered why these classes were named in such a manner. The simple answer  
is "Because JMS did it." The more insightful answer is because the class  
names were too generic and could easily be confused and clash with other  
exceptions, which would force the developer to always use a full qualified  
namespace name. Therefore, the use of the prefix in the class name actually  
becomes a shorthand method for clarification of code intent.

A quick review of the newly added classes reveals that there are a couple  
that are fairly generically named, and could easily conflict with other  
exceptions. The most obvious ones  
are "IllegalStateException", "TransactionInProgressException", "TransactionRolledBackException".  
If a piece of code is performing messaging and database transactions, the  
class names could potentially conflict. Even if they don't conflict, the  
reader of the code is not immediately clear on which exception class is  
actually being handled. Is it an exception thrown by the database provider,  
or by NMS?

Here is a sample bit of code to illustrate the point.

using Apache.NMS;
using Oracle.DataAccess.Client;

public void DoTransactionMsgProcessing()
{
try
{
// Do some Oracle related operations
// Do some NMS related operations
}
catch(TransactionRolledBackException ex)
{
// Is this an Oracle exception, or an NMS exception?
}
catch(NMSException ex)
{
// This is clearly an NMS exception
}
catch(OracleException ex)
{
// This is clearly an Oracle exception.
}
catch(Exception ex)
{
// This is clearly the system-scope class Exception.
}
}

In fact, if one studies the Oracle .Net client API, many of their classes  
are prefixed with "Oracle", even though they are embedded within the  
Oracle.DataAccess.Client namespace. This is because their API designers  
know that the most common usage pattern is to import the entire namespace  
into the scope of a source file using a single using statement at the top  
of the file, and not to use fully qualified namespaces on every usage of a  
class name or interface. Here is a list of Oracle's exception class names:

OracleException
OracleNullValueException
OracleTruncateException
OracleTypeException
OracleXMLSQLException

These are all within the Oracle.DataAccess.Client namespace. By including  
the "Oracle" prefix, it clarifies code intent while avoiding name clashes  
when the namespace is imported with other namespaces. Code intent is  
important. Code will be read many more times than it will be written.

Consistency is also important. This helps both the code reader and writer.  
To have a mix of exceptions classes where some start with NMS and others  
don't, leads to special cases that must be memorized. If there are to be  
some exception classes that begin with NMS (and there already are), and  
there are compelling reasons to have the classes named in such a way, then  
all exception classes should have a consistent name pattern. As shown  
above, Oracle has followed this principal, and it makes a lot of sense.

I am not recommending this naming convention because Oracle does it. I  
simply found (after the fact) that Oracle follows this convention. I am  
recommending this naming convention for the principal of code clarity and  
programmer intent.

To recap, here are the proposed exception class names. There are two lists  
that show what the entire list of exception names will be.

List One
-------------------------
IllegalStateException
InvalidClientIDException
InvalidDestinationException
InvalidSelectorException
MessageEOFException
MessageFormatException
MessageNotReadableException
MessageNotWriteableException
NMSConnectionException
NMSException
NMSSecurityException
ResourceAllocationException
TransactionInProgressException
TransactionRolledBackException


List Two
-------------------------
NMSConnectionException
NMSException
NMSIllegalStateException
NMSInvalidClientIDException
NMSInvalidDestinationException
NMSInvalidSelectorException
NMSMessageEOFException
NMSMessageFormatException
NMSMessageNotReadableException
NMSMessageNotWriteableException
NMSResourceAllocationException
NMSSecurityException
NMSTransactionInProgressException
NMSTransactionRolledBackException

I vote for List Two. I am interested in hearing feedback from other  
developers. I have stated my thoughts, but I am perfectly willing to go  
with List One if everyone wants that for the standard.

Re: Discuss: AMQNET-93

[semog <e....@gmail.com>]

The vote passes with +2 for List One, and +1 for List Two.  The changes have
been applied to the repository.


Timothy Bish wrote:
> 
> +1 for the first list.
> 
> 
> semog wrote:
>> 
>> Well, I think this issue needs to be resolved.  The informal vote and
>> preference is for List One, so I'll adjust the code to match that style.
>> 
>> - Jim
>> 
>> On Fri, Feb 27, 2009 at 2:53 PM, ybronsht <yb...@progress.com> wrote:
>> 
>>>
>>> Jim, I understand your point about Oracle. First of all, we can tell
>>> that
>>> Oracle is also ignorant of the framework guidelines from their naming of
>>> "OracleXMLSQLException". I've actually seen this come up in a more
>>> general
>>> case in Microsoft's own products:
>>>
>>> There's a ServiceDescription class (represents a WSDL document) in the
>>> System.Web.Services.Description in a .Net 2.0 assembly, and a
>>> System.ServiceModel.ServiceDescription class in a WCF (.Net 3.0)
>>> assembly.
>>> Having worked on a WCF product for the past year or so, I've seen them
>>> collide on many occasions. What is done (including in many Microsoft
>>> code
>>> samples) is just a namespace alias:
>>>
>>> using WSDL = System.Web.Services.Description;
>>> ...
>>> var wsdl = new WSDL.ServiceDescription();
>>>
>>> The compiler will force the user to keep the naming unambiguous - that's
>>> not
>>> our job. And if the user wants to type those extra three letters for
>>> visual
>>> clarity, he can do that too - again, not our job. Let's let the user
>>> decide
>>> when those letters need to be there and when they can be done without.
>>> --
>>> View this message in context:
>>> http://www.nabble.com/Discuss%3A-AMQNET-93-tp22255094p22256029.html
>>> Sent from the ActiveMQ - Dev mailing list archive at Nabble.com.
>>>
>>>
>> 
>> 
> 
> 

-- 
View this message in context: http://www.nabble.com/Discuss%3A-AMQNET-93-tp22255094p22461837.html
Sent from the ActiveMQ - Dev mailing list archive at Nabble.com.

Re: Discuss: AMQNET-93

[Timothy Bish <ta...@gmail.com>]

+1 for the first list.


semog wrote:
> 
> Well, I think this issue needs to be resolved.  The informal vote and
> preference is for List One, so I'll adjust the code to match that style.
> 
> - Jim
> 
> On Fri, Feb 27, 2009 at 2:53 PM, ybronsht <yb...@progress.com> wrote:
> 
>>
>> Jim, I understand your point about Oracle. First of all, we can tell that
>> Oracle is also ignorant of the framework guidelines from their naming of
>> "OracleXMLSQLException". I've actually seen this come up in a more
>> general
>> case in Microsoft's own products:
>>
>> There's a ServiceDescription class (represents a WSDL document) in the
>> System.Web.Services.Description in a .Net 2.0 assembly, and a
>> System.ServiceModel.ServiceDescription class in a WCF (.Net 3.0)
>> assembly.
>> Having worked on a WCF product for the past year or so, I've seen them
>> collide on many occasions. What is done (including in many Microsoft code
>> samples) is just a namespace alias:
>>
>> using WSDL = System.Web.Services.Description;
>> ...
>> var wsdl = new WSDL.ServiceDescription();
>>
>> The compiler will force the user to keep the naming unambiguous - that's
>> not
>> our job. And if the user wants to type those extra three letters for
>> visual
>> clarity, he can do that too - again, not our job. Let's let the user
>> decide
>> when those letters need to be there and when they can be done without.
>> --
>> View this message in context:
>> http://www.nabble.com/Discuss%3A-AMQNET-93-tp22255094p22256029.html
>> Sent from the ActiveMQ - Dev mailing list archive at Nabble.com.
>>
>>
> 
> 

-- 
View this message in context: http://www.nabble.com/Discuss%3A-AMQNET-93-tp22255094p22413422.html
Sent from the ActiveMQ - Dev mailing list archive at Nabble.com.

Re: Discuss: AMQNET-93

[Jim Gomes <e....@gmail.com>]

Well, I think this issue needs to be resolved.  The informal vote and
preference is for List One, so I'll adjust the code to match that style.

- Jim

On Fri, Feb 27, 2009 at 2:53 PM, ybronsht <yb...@progress.com> wrote:

>
> Jim, I understand your point about Oracle. First of all, we can tell that
> Oracle is also ignorant of the framework guidelines from their naming of
> "OracleXMLSQLException". I've actually seen this come up in a more general
> case in Microsoft's own products:
>
> There's a ServiceDescription class (represents a WSDL document) in the
> System.Web.Services.Description in a .Net 2.0 assembly, and a
> System.ServiceModel.ServiceDescription class in a WCF (.Net 3.0) assembly.
> Having worked on a WCF product for the past year or so, I've seen them
> collide on many occasions. What is done (including in many Microsoft code
> samples) is just a namespace alias:
>
> using WSDL = System.Web.Services.Description;
> ...
> var wsdl = new WSDL.ServiceDescription();
>
> The compiler will force the user to keep the naming unambiguous - that's
> not
> our job. And if the user wants to type those extra three letters for visual
> clarity, he can do that too - again, not our job. Let's let the user decide
> when those letters need to be there and when they can be done without.
> --
> View this message in context:
> http://www.nabble.com/Discuss%3A-AMQNET-93-tp22255094p22256029.html
> Sent from the ActiveMQ - Dev mailing list archive at Nabble.com.
>
>

Re: Discuss: AMQNET-93

[ybronsht <yb...@progress.com>]

Jim, I understand your point about Oracle. First of all, we can tell that
Oracle is also ignorant of the framework guidelines from their naming of
"OracleXMLSQLException". I've actually seen this come up in a more general
case in Microsoft's own products:

There's a ServiceDescription class (represents a WSDL document) in the
System.Web.Services.Description in a .Net 2.0 assembly, and a
System.ServiceModel.ServiceDescription class in a WCF (.Net 3.0) assembly.
Having worked on a WCF product for the past year or so, I've seen them
collide on many occasions. What is done (including in many Microsoft code
samples) is just a namespace alias:

using WSDL = System.Web.Services.Description;
...
var wsdl = new WSDL.ServiceDescription();

The compiler will force the user to keep the naming unambiguous - that's not
our job. And if the user wants to type those extra three letters for visual
clarity, he can do that too - again, not our job. Let's let the user decide
when those letters need to be there and when they can be done without.
-- 
View this message in context: http://www.nabble.com/Discuss%3A-AMQNET-93-tp22255094p22256029.html
Sent from the ActiveMQ - Dev mailing list archive at Nabble.com.