NOJIRA:  Added javadoc and comments, modest refactor for clarity;  another client hit the issue James fixed a week ago... as long as I was looking at it, wanted to make it more visually different from the broken version