added notes about side effects to JavaDoc