improve logging and add more javadoc