You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I'm a Java™ programmer seeking guidance on best practice and recommended Java™ programming idioms. Ordinarily, my first inclination is to defer to the most authoritative references for the Java™ programming language.
However, library authors can sometimes offer compelling rationale to do otherwise.
RuntimeException and its subclasses are unchecked exceptions. Unchecked exceptions do NOT need to be declared in a method or constructor's throws clause if they can be thrown by the
execution of the method or constructor and propagate outside
the method or constructor boundary
…
…
Run-time exception classes are exempted because, in the judgment of
the designers of the Java programming language, having to declare such exceptions would not aid significantly in establishing the correctness of programs. Many of the operations and constructs of
the Java programming language can result in exceptions at run time.
The information available to a Java compiler, and the level of analysis
a compiler performs, are usually not sufficient to establish that such
run-time exceptions cannot occur, even though this may be obvious to the
programmer. Requiring such exception classes to be declared would simply be an irritation to programmers
…
The Issue
TL;DR — It's puzzling why some Java™ SDK for CloudEvents methods are declared with a throws RuntimeException clause.
To elaborate
I have tried to reason about what this library's API designers might have intended to communicate to callers by exposing the atypical public signatures in question. Several hypothetical questions arose. Here are three examples…
What does this project's authors intend callers to do when calling methods declared with throws RuntimeException?
What do you foresee would happen if callers ignore (don't handle) your methods' throws RuntimeExceptions?
What, originally, did you foresee would happen for callers if those throws RuntimeException were never declared?
…
Which methods?
All overloaded CloudEventContextWriter.withContextAttribute(...)methods havethrows CloudEventRWException declarations…
Interestingly, the two methodsCloudEventContextReaderAdapter.readAttributes()CloudEventContextReaderAdapter.readExtensions()are both declared withthrows RuntimeException; the superclass of CloudEventRWException…
…
public void readAttributes(CloudEventContextWriter writer) throws RuntimeException
…
public void readExtensions(CloudEventContextWriter writer) throws RuntimeException
…
// This should never happen because we build that map only through our builders
throw new IllegalStateException("Illegal value inside extensions map: " + key + " " + value);
…
CloudEventContextReaderAdapter.readContext(CloudEventContextWriter)calls both of its sibling methods. However, it IS declared with throws CloudEventRWException…
public void readContext(CloudEventContextWriter writer) throws CloudEventRWException
Or is it just me?
The system I'm currently analyzing and will eventually implement, potentially may consume the public API of the Java™ SDK for CloudEvents.
For not only my project specifically, I imagine it would be helpful for all consuming projects in general to understand the rationale behind this SDK's atypical idiom of explicitly declaring public methods with throws RuntimeException.
Proposed Solution
There's more than one alternative that I presume would have value to the entire community. Here are just two examples…
Add clear explanations in the Java™ SDK for CloudEvents Javadoc
Nothing complicated; simply something that clarifies the methods in question's rationale for taking the road less traveled
Currently, there is nothing documenting why throws RuntimeException is necessary
Remove the explictly-declared throws RuntimeException clauses
But add Javadoc that uses the @throws annotation appropriately to document what callers of the method should expect
???
The text was updated successfully, but these errors were encountered:
As CloudEvents is a library, people consume, it makes sense it should have a nice hierarchy of checked exceptions. That would allow people to properly act upon failures.
Context
I'm a Java™ programmer seeking guidance on best practice and recommended Java™ programming idioms. Ordinarily, my first inclination is to defer to the most authoritative references for the Java™ programming language.
However, library authors can sometimes offer compelling rationale to do otherwise.
Java™ SE 8 Javadoc for
RuntimeException
:Java™ Language Specification (JLS)
The Issue
TL;DR — It's puzzling why some Java™ SDK for CloudEvents methods are declared with a
throws RuntimeException
clause.To elaborate
I have tried to reason about what this library's API designers might have intended to communicate to callers by exposing the atypical public signatures in question. Several hypothetical questions arose. Here are three examples…
throws RuntimeException
?throws RuntimeException
s?throws RuntimeException
were never declared?Which methods?
All overloaded
CloudEventContextWriter.withContextAttribute(...)
methods havethrows CloudEventRWException
declarations…Interestingly, the two methods
CloudEventContextReaderAdapter.readAttributes()
CloudEventContextReaderAdapter.readExtensions()
are both declared withthrows RuntimeException
; the superclass ofCloudEventRWException
…CloudEventContextReaderAdapter.readContext(CloudEventContextWriter)
calls both of its sibling methods. However, it IS declared withthrows CloudEventRWException
…Or is it just me?
The system I'm currently analyzing and will eventually implement, potentially may consume the public API of the Java™ SDK for CloudEvents.
For not only my project specifically, I imagine it would be helpful for all consuming projects in general to understand the rationale behind this SDK's atypical idiom of explicitly declaring public methods with
throws RuntimeException
.Proposed Solution
There's more than one alternative that I presume would have value to the entire community. Here are just two examples…
throws RuntimeException
is necessarythrows RuntimeException
clauses@throws
annotation appropriately to document what callers of the method should expectThe text was updated successfully, but these errors were encountered: