some refactoring and javadocs