Add some javadocs, plus more precisely narrow where an exception is caught.
Mark a fail-over case as such.
fix some javadoc links.