added some validation and javadoc