substantial API refinement and javadocs