Review completely the javalib

Could you add this as a comment? (I mean that we flush in opposition to what the JavaDoc says)