MySQL Bugs: #52017: API documentation doesn't indicate which methods throw which Exceptions

Bug #52017	API documentation doesn't indicate which methods throw which Exceptions
Submitted:	12 Mar 2010 20:10	Modified:	6 Nov 2013 11:11
Reporter:	Todd Farmer (OCA)	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Cluster: Cluster/J	Severity:	S3 (Non-critical)
Version:	7.1.1	OS:	Any
Assigned to:	Assigned Account	CPU Architecture:	Any

Description:
All domain Exceptions for Cluster/J core subclass RuntimeException, an uncaught exception.  This raises architectural concerns for me, but my immediate concern here is the lack of documentation around which Exceptions can be thrown from which methods.  Because RuntimeExceptions and its subclasses do not need to be explicitly declared or caught by invoking code, there's no clear contract provided to the Cluster/J application developer so that they can code defensively.

I'll argue that Cluster/J needs to not subclass RuntimeException, and to provide a concrete API contract including potential thrown Exceptions, but at the very minimum, the documentation needs to indicate which methods throw which domain Exceptions.

How to repeat:
See Cluster/J API reference documentation.

Suggested fix:
See above.

I've pushed a change that adds javadoc to ClusterJException to distinguish among the three cases:
ClusterJFatalUserException for errors during acquiring a SessionFactory
ClusterJUserException for user errors during operation
ClusterJDatastoreException for errors reported by the cluster
ClusterJFatalInternalException for internal errors

Using saved parent location: bzr+ssh://crussell@bk-internal.mysql.com/bzrroot/clusterj/
 M  clusterj-api/src/main/java/com/mysql/clusterj/ClusterJException.java                                                                                                                                                            
 M  clusterj-core/src/main/java/com/mysql/clusterj/core/metadata/DomainTypeHandlerImpl.java
 M  clusterj-tie/src/main/java/com/mysql/clusterj/tie/Utility.java
All changes applied successfully.                                                                                                                                                                                                   
Now on revision 232.

Thank you for your bug report. This issue has been committed to our source repository of that product and will be incorporated into the next release.

If necessary, you can access the source repository and build the latest available version, including the bug fix. More information about accessing the source trees is available at

    http://dev.mysql.com/doc/en/installing-source.html