Change OrekitException into a subtype of RuntimeException
- Change
The change is related to error handling. Currently, Orekit has one
main
exception, OrekitException. This is a checked exception, so callers
(i.e.
you when you develop an application on top of the library) have to
either
let it bubble upward up to the main or have to catch it and act
accordingly.
As most of Orekit methods declare to throw this exception, most of
calling
code has to do this choice: declare or catch.
User code can also sometimes wrap up some Orekit code in other
frameworks
and have to respect the API of these frameworks. In this case, the
OrekitException must always be caught and probably wrapped within a
RuntimeException so it is not "seen" by the framework. One typical
example
is the use of Java 8 streams and lambda functions, and these do not
allow
exception, so some cumbersome wrapping code has to be set up.
- Context
Discussions about this change can be viewed here :
https://www.orekit.org/wws/arc/orekit-developers/2018-07/msg00000.html
This discussion identified several potential implementations. A poll
took place on orekit-users mailing list which can be consulted here :
https://www.orekit.org/wws/arc/orekit-users/2018-07/msg00017.html
- Implementation
The community decided that OrekitException should inherit from RuntimeException (option 2 in the poll), since this is the easiest solution to implement, while hopefully remaining very usable.
## Identified tasks
- make OrekitException extend RuntimeException
- remove the now unnecessary "throws OrekitException" from all Orekit methods signatures
- modify the javadoc of all methods previously throwing OrekitExceptions ? Or keep the info, which is still useful but could become more difficult to maintain ? >to be discussed
(from redmine: issue id 484, created on 2018-07-18)
- Changesets:
- Revision 79c780bc by Yannick Jeandroz on 2018-08-03T08:23:48Z:
Make OrekitException extend RuntimeException.
This change has been discussed on both the developers and users lists,
and results from a poll among users. The rationale of the change is
base on three observations:
1) before the change OrekitException was a checked exception.
Therefore, calling features that throws one from some higher
level library may imply wrapping the checked exception. This
typically occurs when optimizing some parts (maneuvers, orbit
determination) with Hipparchus calling Orekit, or calling an
Orekit function using Java 8 lambda functions.
2) most if not all Orekit features do throw such an exception,
so the information to the user that a specific function does
throws an OrekitException was pointless as all of them do.
3) in many cases it is impossible to recover from these exceptions
(for example if UTC-TAI or JPL data is missing, one can barely do
anything in Orekit). Therefore, basically all exceptions thrown
from Orekit classes bubbled up to the top level application and
were caught there just to be displayed at the end.
Observations 2 and 3 lead to think that unchecked exceptions are better
suited than unchecked exceptions for Orekit expected use cases, and
observation 1 lead to think that unchecked exceptions would greatly
simplify user code.
So we moved from checked exceptions to unchecked exceptions.
Fixes #484.
- Revision 79c780bc by Yannick Jeandroz on 2018-08-03T08:23:48Z:
Make OrekitException extend RuntimeException.
This change has been discussed on both the developers and users lists,
and results from a poll among users. The rationale of the change is
base on three observations:
1) before the change OrekitException was a checked exception.
Therefore, calling features that throws one from some higher
level library may imply wrapping the checked exception. This
typically occurs when optimizing some parts (maneuvers, orbit
determination) with Hipparchus calling Orekit, or calling an
Orekit function using Java 8 lambda functions.
2) most if not all Orekit features do throw such an exception,
so the information to the user that a specific function does
throws an OrekitException was pointless as all of them do.
3) in many cases it is impossible to recover from these exceptions
(for example if UTC-TAI or JPL data is missing, one can barely do
anything in Orekit). Therefore, basically all exceptions thrown
from Orekit classes bubbled up to the top level application and
were caught there just to be displayed at the end.
Observations 2 and 3 lead to think that unchecked exceptions are better
suited than unchecked exceptions for Orekit expected use cases, and
observation 1 lead to think that unchecked exceptions would greatly
simplify user code.
So we moved from checked exceptions to unchecked exceptions.
Fixes #484.
- Revision 6eea462f by Yannick Jeandroz on 2018-08-03T08:24:31Z:
Removed the now useless catch (OrekitException).
Fixes #484.
- Revision 6eea462f by Yannick Jeandroz on 2018-08-03T08:24:31Z:
Removed the now useless catch (OrekitException).
Fixes #484.
- Revision 93922600 by Yannick Jeandroz on 2018-08-03T08:44:37Z:
Removed all uses of OrekitExceptionWrapper class.
Fixes #484.
- Revision 93922600 by Yannick Jeandroz on 2018-08-03T08:44:37Z:
Removed all uses of OrekitExceptionWrapper class.
Fixes #484.
- Revision c4510d7d by Luc Maisonobe on 2018-08-03T08:47:19Z:
Deprecated OrekitExceptionWrapper.
The class must be kept until next major version as it may be referenced
for existing user code.
Fixes #484.
- Revision c4510d7d by Luc Maisonobe on 2018-08-03T08:47:19Z:
Deprecated OrekitExceptionWrapper.
The class must be kept until next major version as it may be referenced
for existing user code.
Fixes #484.
- Revision dab4c595 by Yannick Jeandroz on 2018-08-03T09:29:49Z:
Removed throws OrekitException and javadoc.
Fixes #484
- Revision dab4c595 by Yannick Jeandroz on 2018-08-03T09:29:49Z:
Removed throws OrekitException and javadoc.
Fixes #484
- Revision 30cf631e by Yannick Jeandroz on 2018-08-03T12:08:04Z:
Removed unused imports.
Fixes #484
- Revision 30cf631e by Yannick Jeandroz on 2018-08-03T12:08:04Z:
Removed unused imports.
Fixes #484
- Uploads:
- 1-Made_OrekitException_a_RuntimeException.patch
- 2-Removed_the_now_useless__catch__OrekitException__.patch
- 4-Removed_OrekitExceptionWrapper_class.patch
- 3-Removed_occurrences_of_OrekitExceptionWrapper.patch
- 6-Removed_unused_imports.patch
- 5-Removed__throws_OrekitException__and_javadoc.patch
- 0001-Documented-import-of-Orekit-in-IntelliJ.patch