fixed comment
code cleanup

- shuffle things around
- throw more appropriate exception
- respect portal URL scheme
polishing
extract class refactorings