exceptions in wsrp4j

[Andrew Petro <an...@yale.edu>]

In JIRA, Don Brown mentioned:

"WSRP4J really needs to improve its exception reporting.  I had to start 
injecting debugging code to get the stacktrace for this exception."

http://issues.apache.org/jira/browse/WSRP4J-74#action_12356145

I've been thinking about how wsrp4j exceptions could be improved.

WSRP4j uses error codes and an exception helper class to centralize 
exception message generation.  This has advantages in making the 
exception messages localizable without hacking the .java (in a 
messages.properties file).

Current advantages/features of the exception generation approach:

1) Exceptional conditions are categorized broadly as "common", 
"producer", "provider", and "consumer" and specifically by an error code.

2) Error messages are customizable / localizeable without touching the .java

3) WSRPExceptions can be translated to RemoteExceptions


However, the approach of having one WSRPException for all needs and 
parameterizing it with an error code has limitations.

One limitation is that it makes the exception weakly typed -- there is 
not a rich hierarchy of exceptions that can be selectively caught, nor 
is relevant context besides stack trace captured with particular exceptions.

For example, when a WSRPException is thrown because a URL is malformed, 
it would be helpful to include the malformed URL right in the exception 
message.  It might be even more helpful to have a strongly typed 
exception extending WSRPException which bears an accessor method 
exposing the broken URL.

I wonder if going a route of having an exception hierarchy with objects 
representing the various exceptional conditions would be more effective 
than the current practice of using integer constants to characterize 
exceptional conditions.  Particular strongly typed Exceptions 
representing particular exceptional conditions would take additional 
constructor arguments which would provide content to the localizeable 
template message.  For instance, the PropertyFileNotFoundException would 
take as a constuctor argument the name of the properties file that was 
not found and use that value in populating a potentially localized 
template message.

Strongly typed WSRPExceptions could take responsibility for implementing 
a superclass-declared method for producing the RemoteException 
translation of a particular WSRPException.  This associates the code for 
translating a particular kind of exceptional condition with the object 
implementation representing that exceptional condition.  Imho a more 
attractive design than a case statement in a static translation service.

Advantages of using an exception hierarchy:
1) Exceptional conditions can continue to be categorized broadly as 
"common", "consumer", "provider", or "producer" by means of the 
coarse-granularity root exceptions in the hierarchy under WSRPException 
and more specifically by the specific class of the exception 
implementation.  (Maybe whether this is worth doing is worth re-thinking.)

2) Error messages can continue to be customizable by the exception 
objects implementing getMessage() to consider a localizable template.  
These messages can be improved by inserting context in the exception 
messages where appropriate.  "Unable to initialize portlet management 
port." becomes "Unable to initialize portlet management port: [{actual 
URL that could not be initialized goes here}]".

3) WSRPExceptions can continue to be translatable into RemoteExceptions, 
this being declared as an overridable method of WSRPException itself.  
WSRPExceptions can accept the generic RemoteException translation or can 
override the method to implement a more specific translation.

4) Java classes for specific exceptional conditions provides a natural 
place to document what is meant by the exceptional condition (in the 
JavaDoc of the exception).

5) Stack traces become simpler to interpret, with exceptions originating 
from the place in the code that experienced the exceptional condition 
(rather than from a helper utility class for exception generation).

6) APIs within wsrp4j can become more specific about their exception 
throwing behavior.  The Utility class method for parsing a Properties 
file needn't declare the generic WSRPException when it will only throw 
PropertiesFileNotFoundException.


I've prepared a quick code sketch of what converting to an exception 
hierarchy might look like.  The code sketch shows an exception hierarchy 
pretty closely representing the error conditions enumerated in the 
present sandbox.  It also shows WSRPException subclasses implementing 
their own translation to RemoteExceptions and capturing state related to 
particular exceptional conditions (What portlet handle was it that 
wasn't found?)

This sketch doesn't carefully retain the categorization of exceptions as 
consumer, producer, provider, or common (though this could be done as 
noted above).  This sketch also doesn't provide a way to localize the 
message templates, though this could also be done.

Changes are applied only to the sandbox code in the sketch:

http://tp.its.yale.edu/~awp9/published/apache/wsrp4j/exceptions/

How much thought has gone into not having an exception hierarchy in 
wsrp4j?  Is introducing an exception hierarchy and more strongly typing 
exceptional conditions a good direction to go in this project?

Imho, there are important opportunities here to better capture the state 
around and report on exceptional conditions, to better document what 
exceptional conditions are expected and handled where and how.

I hope the code sketch can help support fruitful discussion of how best 
to realize these opportunities.

Andrew