client now keeps persistent state, updated javadoc