this closes JCLOUDS-737

cc @adriancole could please review it?
can do this later, but I would delete all these javadoc. they don't add clarity of any kind.