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.
