activemq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From e.se...@gmail.com
Subject Discuss: AMQNET-93
Date Fri, 27 Feb 2009 21:47:28 GMT
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.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message