Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Make some JavaThemis exceptions unchecked (cossacklabs#563)
* Make some JavaThemis exceptions unchecked
Checked exceptions are commonly considered a design mistake in Java
standard library [1]. They have some limited uses, but generally they
do not provide safe and ergonomic interface for the users because they
are often misunderstood. Is is common to use checked exceptions in
situations where unchecked exceptions are more approriate. This leads
to exceptions that cannot be handled by the application and it is really
common to ignore ("fix") them by adding "throws Exception" specifier
because you can't be bothered to enumerate a dozen of concrete classes
of internal library errors. Either way it is not better than using
unchecked exceptions in the first place.
Unchecked exceptions are intended for system faults and programming
errors which are generally not recoverable by the application [2].
For example, using a method incorrectly, not checking for "null" when
it should be checked for, providing invalid argument values, etc.
These are generally not under contol of the application, in the sense
that the user cannot do something to avoid this failure other than
fixing application logic (or, well, circumenting the faulty code path).
Checked exceptions are intended to be used for recoverable errors [2].
That is, something that the application can control and influence.
For example, invalid user input can cause a checked exception because
this is an expected situation (the user can make mistakes and this is
not something that application can generally prevent in code). However,
the application can control the user and instruct them to give correct
input, or at least tell the user that theinput is incorrect. That is,
the application is expected to always handle checked exception in some
way, and there should be a catch clause somewhere in the middle, not
only on the top level for possible run-time exceptions.
[1]: http://literatejava.com/exceptions/checked-exceptions-javas-biggest-mistake/
[2]: https://docs.oracle.com/javase/tutorial/essential/exceptions/runtime.html
With this in mind, convert the following com.cossacklabs.themis
exceptions into runtime, unchecked variants:
- NullArgumentException - it is used to indicate that the programmer
passed a null value where it should not be passed, and this will
cause a NullPointerException later. In fact, NullArgumentException
is now a subclass of NullPointerException as it indicates misuse
of null values.
- InvalidArgumentException - it is used to indicate that the programmer
has passed an invalid argument to the method: an unknown constant,
an empty buffer that must not be empty, or some other violation of
the method contract. It is a subclass of IllegalArgumentException now.
- KeyGenerationException - it is used to indicate internal failure in
Themis key generation routines. This is not something under user
control and key generation does not have any input that can change
its behavior. This error can be caused either by a bug in Themis Core
or by a misconfigured cryptographic backed. Both situations cannot be
recovered by the application.
Note, however, that SecureCellException, SecureMessageWrapException,
SecureSessionException, and SecureCompareException are still checked.
These exceptions are used to indicate issues with user-provided data:
key material, data messages, etc. These are expected failures and should
be handled by the application somehow.
* Throw RuntimeException on UTF-16 conversion errors
Convert UnsupportedEncodingException into RuntimeException in interfaces
that expect Strings and unconditionally serialize them as UTF-16 bytes.
If the implementation does not support UTF-16 -- which is highly
unlikely, given that Java pioneered Unicode and UTF-16 specifically --
then the user application cannot do anything about it (other that
rewrite JavaThemis code). This is not an error with user input. Themis
does not give the user an option to select encoding and always uses
UTF-16, so the user application cannot recover from this error.
* Remove "throws" specs for unchecked exceptions
After these adjustments, update the "throws" clauses in Themis code and
remove all unchecked exceptions from them. This allows user applications
to not handle these exceptions immediately. (Though they can still leave
"throws" specifications in their code if they wish to. Our tests do,
for example, because I can't be bothered to update them without doing
a complete rewrite for readability.)
* Wrap some checked exceptions into runtime exceptions
Drop more "throws" specs from Secure Session and Secure Comparator
interfaces by wrapping some of the exceptions into appropriate runtime
exceptions.
Secure Session and Secure Comparator throw checked exceptions in many
places where user input cannot cause failures. For example, the user
cannot recover from a failure to create Secure Session object. These
errors should cause unchecked, runtime exceptions.
However, in some places checked exceptions are warranted: such as when
wrapping and unwrapping Secure Session messages, or when Secure
Comparator protocol exchange is processed. Here we leave checked
exceptions and indicate them with "throws" specs.
* Avoid throwing UnsupportedEncodingException
Use a different overload of String.getBytes() that does not involve
charset lookup (and possible "unknown encoding" error).- Loading branch information
